پرش به مطلب اصلی

TypeScript SDK

XLADA هیچ SDK جداگانهٔ منتشرشده‌ای به نام XLADA ندارد. این مانع کار نمی‌شود: API این فورک با API Remnawave یکسان است — همان مسیرها، همان طرح‌های درخواست و پاسخ. بنابراین تایپ‌ها و قراردادهای Remnawave سازگارند و کلاینت HTTP در چند خط ساخته می‌شود.

نصب​

برای نمونه‌های زیر fetch استاندارد کافی است که در Node.js 18+ و در مرورگر موجود است. اگر به axios عادت دارید:

npm install axios

SDK رسمی Remnawave — @remnawave/backend-contract — فقط شامل تایپ‌ها و طرح‌های zod است، بدون کلاینت HTTP:

npm install @remnawave/backend-contract

در سورس‌های پنل همان کتابخانهٔ قراردادها در apps/backend/libs/contract قرار دارد (نسخهٔ فرانت‌اند در apps/frontend/vendor/backend-contract) و @xlada/backend-contract نامیده می‌شود. در npm منتشر نمی‌شود: آن را به‌عنوان وابستگی محلی مخزن متصل کنید ("@xlada/backend-contract": "file:./vendor/backend-contract").

تطابق نسخه‌ها

نسخهٔ قرارداد را به نسخهٔ پنل گره بزنید. قرارداد و پنل با چرخه‌های متفاوتی توسعه می‌یابند، بنابراین نسخهٔ «آخرین» تایپ‌ها همیشه دقیقاً سرور شما را توصیف نمی‌کند.

کلاینت پایه​

پنل انتظار Authorization: Bearer <token> را دارد. اگر مستقیماً و از شبکهٔ داخلی به پنل دسترسی می‌گیرید، هدرهای پروکسی را اضافه کنید — middleware پنل بدون X-Forwarded-For و X-Forwarded-Proto: https اتصال را قطع می‌کند.

const PANEL_URL = process.env.XLADA_PANEL_URL ?? 'https://panel.example.com';
const API_TOKEN = process.env.XLADA_API_TOKEN ?? '';

async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
    const res = await fetch(`${PANEL_URL}${path}`, {
        ...init,
        headers: {
            'Content-Type': 'application/json',
            Authorization: `Bearer ${API_TOKEN}`,
            'X-Forwarded-For': '127.0.0.1',
            'X-Forwarded-Proto': 'https',
            ...init.headers,
        },
    });

    if (!res.ok) {
        throw new Error(`${res.status} ${res.statusText}: ${await res.text()}`);
    }

    return (await res.json()) as T;
}

احراز هویت​

دو راه برای گرفتن توکن وجود دارد.

JWT مدیر — عمر محدودی دارد (JWT_AUTH_LIFETIME، از 12 تا 168 ساعت) و با متد POST /api/auth/login صادر می‌شود:

curl -sX POST https://panel.example.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "گذرواژه"}'

پاسخ شامل accessToken است:

{
  "response": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

توکن API — برای اسکریپت‌ها و یکپارچه‌سازی‌ها. با متد POST /api/tokens ساخته می‌شود (در رابط کاربری — تنظیمات → API Tokens) و در همان هدر Authorization فرستاده می‌شود:

curl -sX POST https://panel.example.com/api/tokens \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "ci", "expiresInDays": 365}'

توکن آماده در فیلد response.token می‌آید و فقط یک بار نشان داده می‌شود. فهرست حوزه‌های موجود را GET /api/tokens/scopes برمی‌گرداند.

فهرست کاربران​

خروجی صفحه‌بندی‌شده: start — جابه‌جایی، size — اندازهٔ صفحه (از 1 تا 1000، به‌طور پیش‌فرض 25).

interface GetUsersResponse {
    response: {
        users: Array<{
            id: number;
            username: string;
            status: 'ACTIVE' | 'DISABLED' | 'LIMITED' | 'EXPIRED';
            shortUuid: string;
            expireAt: string;
        }>;
        total: number;
    };
}

const { response } = await api<GetUsersResponse>('/api/users?start=0&size=25');

for (const user of response.users) {
    console.log(user.username, user.status, user.expireAt);
}
console.log(`مجموع: ${response.total}`);

ایجاد کاربر​

POST /api/users پارامتر username را می‌پذیرد (3–36 نویسه، فقط حروف لاتین، ارقام، _ و -) و expireAt اجباری در قالب ISO 8601.

const created = await api<{ response: { id: number; shortUuid: string } }>(
    '/api/users',
    {
        method: 'POST',
        body: JSON.stringify({
            username: 'john_doe',
            status: 'ACTIVE',
            expireAt: '2026-01-17T15:38:45.065Z',
            trafficLimitBytes: 0,
            trafficLimitStrategy: 'NO_RESET',
        }),
    },
);

console.log(created.response.shortUuid);

دریافت نود​

یک نود — با uuid آن، فهرست — بدون پارامتر:

const { response: node } = await api<{
    response: { name: string; address: string; port: number | null; isConnected: boolean };
}>(`/api/nodes/${nodeUuid}`);

console.log(node.name, `${node.address}:${node.port}`, node.isConnected);

تایپ‌ها را از کجا بگیریم​

مشخصات کامل — 162 مسیر و 29 برچسب — در صفحهٔ API Specification و در فایل static/openapi.json مخزن پنل قرار دارد. از آن می‌توان .d.ts تولید کرد:

npx openapi-typescript ./openapi.json -o ./src/xlada-api.d.ts
نکته

تایپ‌ها را از مشخصات دقیقاً همان نسخهٔ پنلی تولید کنید که نصب کرده‌اید: میان انتشارها مجموعهٔ فیلدها تغییر می‌کند.

گام بعدی​