@windmc/js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WindMC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# wind-js-client
+Официальная клиентская библиотека для работы с API Wind. Поддерживает Node.js и TypeScript.
+
+## Установка
+
+```bash
+npm install @windmc/js
+```
+
+## Конфигурация
+
+```ts
+import { WindClient } from "@windmc/js";
+
+const client = new WindClient({
+  clientId: "ВАШ_CLIENT_ID",
+  clientSecret: "ВАШ_CLIENT_SECRET",   // для OAuth
+  redirectUri: "https://yoursite.example/callback",
+  appToken: "ВАШ_APP_TOKEN",           // для Billing
+  webhookSecret: "ВАШ_WEBHOOK_SECRET", // для проверки вебхуков
+});
+```
+
+## OAuth авторизация
+
+```ts
+// 1. Получить ссылку для входа
+const url = client.getAuthorizeUrl(["identify", "bank"]);
+// → https://windmc.su/oauth2/authorize?...
+
+// 2. Обменять code на токены
+const tokens = await client.exchangeCode(code);
+
+// 3. Получить данные пользователя
+const user = await client.getUser(tokens.access_token);
+console.log(user.nickname, user.avatar);
+```
+
+### PKCE (для SPA и мобильных приложений)
+
+Если ваше приложение не может безопасно хранить `clientSecret` (браузер, мобильное
+приложение), используйте PKCE вместо секрета — `clientSecret` в конфиге при этом
+можно не указывать:
+
+```ts
+import { WindClient, generatePKCE } from "@windmc/js";
+
+const client = new WindClient({
+  clientId: "ВАШ_CLIENT_ID",
+  redirectUri: "https://yourapp.example/callback",
+});
+
+// 1. Сгенерировать пару и сохранить codeVerifier (например, в сессии/cookie)
+const { codeVerifier, codeChallenge } = generatePKCE();
+const url = client.getAuthorizeUrl(["identify"], undefined, codeChallenge);
+
+// 2. После редиректа обменять code на токены с помощью сохранённого codeVerifier
+const tokens = await client.exchangeCode(code, codeVerifier);
+
+// 3. refreshToken() и revokeToken() для PKCE-токенов работают без clientSecret
+const refreshed = await client.refreshToken(tokens.refresh_token);
+```
+
+## Доступные scopes
+
+| Scope        | Описание                                |
+|--------------|-----------------------------------------|
+| `identify`   | Никнейм, UUID, роли                     |
+| `bank`       | Счета и транзакции                      |
+| `bank:charge`| Списание средств (требует подтверждения)|
+| `communities`| Список сообществ пользователя          |
+| `friends`    | Список друзей                           |
+
+## Методы
+
+### OAuth / пользователь
+
+```ts
+client.getAuthorizeUrl(scopes, state?)         // URL авторизации
+client.exchangeCode(code)                      // code → tokens
+client.refreshToken(refreshToken)              // обновить токен
+client.revokeToken(token)                      // отозвать токен
+client.getUser(accessToken)                    // scope: identify
+client.getBank(accessToken)                    // scope: bank
+client.getBankTransactions(accessToken, limit?)// scope: bank
+client.getCommunities(accessToken)             // scope: communities
+client.getFriends(accessToken)                 // scope: friends
+client.createCharge(accessToken, payload)      // scope: bank:charge
+client.getCharge(accessToken, chargeId)        // scope: bank:charge
+```
+
+### Billing (App Token)
+
+```ts
+// Создать счёт — вернёт payUrl для редиректа пользователя
+const bill = await client.createBill({
+  toAccountId: 1001,
+  amount: 500,
+  comment: "Оплата",
+  webhookUrl: "https://yoursite.example/webhooks/wind",
+  returnUrl: "https://yoursite.example/success",
+});
+// → { billId, payUrl, expiresAt }
+
+// Проверить статус счёта
+const status = await client.getBill(bill.billId);
+// → { status: "pending" | "paid" | "expired", ... }
+```
+
+### Вебхуки
+
+Счёт действует 10 минут. После оплаты Wind отправляет POST-запрос на `webhookUrl` с заголовком `X-Signature: sha256=<hmac>`.
+
+```ts
+// Express: читать тело как raw buffer
+app.use("/webhooks/wind", express.raw({ type: "application/json" }));
+
+app.post("/webhooks/wind", (req, res) => {
+  const signature = req.headers["x-signature"];
+
+  let payload;
+  try {
+    payload = client.parseWebhook(req.body.toString(), signature);
+  } catch {
+    return res.status(401).json({ error: "Неверная подпись" });
+  }
+
+  if (payload.event === "bill.paid") {
+    console.log(`Оплачен счёт ${payload.billId} на сумму ${payload.amount}`);
+  }
+
+  res.status(200).json({ ok: true });
+});
+```
+
+## Примеры
+
+Готовые примеры в директории [`example/`](./example):
+- `oauth-login` — OAuth авторизация с Express
+- `create-bill` — Создание счёта на оплату
+- `webhook` — Обработка вебхуков
+
+## Сборка
+
+```bash
+npm run build
+```

package/dist/error.d.ts

@@ -0,0 +1,5 @@
+export declare class WindError extends Error {
+    statusCode?: number;
+    details?: object;
+    constructor(message: string, statusCode?: number, details?: object);
+}

package/dist/error.js

@@ -0,0 +1,9 @@
+// WindError © Винд 2026
+export class WindError extends Error {
+    constructor(message, statusCode, details) {
+        super(message);
+        this.name = "WindError";
+        this.statusCode = statusCode;
+        this.details = details;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import type { Config, WindScope, AccessTokenResponse, User, BankResponse, TransactionsResponse, CommunitiesResponse, FriendsResponse, ChargeRequest, CreateChargePayload, CreateBillPayload, CreateBillResponse, BillStatusResponse, WebhookPayload } from "./types.js";
+export * from "./types.js";
+export { WindError } from "./error.js";
+/**
+ * Генерирует пару PKCE (code_verifier + code_challenge, метод S256).
+ * Используйте для публичных клиентов (SPA, мобильные приложения), у которых
+ * нет безопасного места для хранения clientSecret: code_verifier храните
+ * у себя (например, в сессии) до обмена кода на токен, code_challenge —
+ * передайте в {@link WindClient.getAuthorizeUrl}.
+ */
+export declare function generatePKCE(): {
+    codeVerifier: string;
+    codeChallenge: string;
+};
+export declare class WindClient {
+    private readonly config;
+    constructor(config: Config);
+    /**
+     * Возвращает URL для авторизации пользователя.
+     * @param scopes        - массив запрашиваемых scopes
+     * @param state         - произвольная строка для защиты от CSRF
+     * @param codeChallenge - PKCE code_challenge (см. {@link generatePKCE}); нужен для публичных
+     *                        клиентов (SPA, мобильные приложения), у которых нет clientSecret
+     */
+    getAuthorizeUrl(scopes: WindScope[], state?: string, codeChallenge?: string): string;
+    /**
+     * Обменивает authorization code на токены.
+     * @param code         - код из redirect_uri
+     * @param codeVerifier - PKCE code_verifier, если авторизация запускалась с codeChallenge
+     */
+    exchangeCode(code: string, codeVerifier?: string): Promise<AccessTokenResponse>;
+    /**
+     * Обновляет access token с помощью refresh token.
+     * Для PKCE-токенов (публичный клиент без clientSecret) секрет не требуется.
+     */
+    refreshToken(refreshToken: string): Promise<AccessTokenResponse>;
+    /**
+     * Отзывает токен.
+     * Для PKCE-токенов (публичный клиент без clientSecret) секрет не требуется.
+     */
+    revokeToken(token: string): Promise<void>;
+    /**
+     * Возвращает информацию о текущем пользователе.
+     * Требует scope: identify
+     */
+    getUser(accessToken: string): Promise<User>;
+    /**
+     * Возвращает банковские счета пользователя.
+     * Требует scope: bank
+     */
+    getBank(accessToken: string): Promise<BankResponse>;
+    /**
+     * Возвращает транзакции пользователя.
+     * Требует scope: bank
+     */
+    getBankTransactions(accessToken: string, limit?: number): Promise<TransactionsResponse>;
+    /**
+     * Возвращает сообщества пользователя.
+     * Требует scope: communities
+     */
+    getCommunities(accessToken: string): Promise<CommunitiesResponse>;
+    /**
+     * Возвращает список друзей пользователя.
+     * Требует scope: friends
+     */
+    getFriends(accessToken: string): Promise<FriendsResponse>;
+    /**
+     * Создаёт запрос на списание средств.
+     * Требует scope: bank:charge
+     */
+    createCharge(accessToken: string, payload: CreateChargePayload): Promise<ChargeRequest>;
+    /**
+     * Возвращает статус запроса на списание.
+     * Требует scope: bank:charge
+     */
+    getCharge(accessToken: string, chargeId: string): Promise<ChargeRequest>;
+    /**
+     * Создаёт счёт на оплату. Использует App Token (X-Client-Id + Bearer).
+     * После создания пользователь перейдёт по payUrl для оплаты.
+     */
+    createBill(payload: CreateBillPayload): Promise<CreateBillResponse>;
+    /**
+     * Возвращает информацию о счёте по его ID.
+     */
+    getBill(billId: string): Promise<BillStatusResponse>;
+    /**
+     * Проверяет подпись входящего вебхука.
+     * @param rawBody   - тело запроса как строка (до JSON.parse)
+     * @param signature - значение заголовка X-Signature
+     */
+    verifyWebhookSignature(rawBody: string, signature: string): boolean;
+    /**
+     * Парсит тело вебхука с проверкой подписи.
+     * Бросает WindError если подпись неверна.
+     */
+    parseWebhook(rawBody: string, signature: string): WebhookPayload;
+    private request;
+}

package/dist/index.js

@@ -0,0 +1,265 @@
+// WindClient © Винд 2026
+import crypto from "node:crypto";
+import { WindError } from "./error.js";
+export * from "./types.js";
+export { WindError } from "./error.js";
+const DEFAULT_API_URL = "https://api.windmc.su";
+const DEFAULT_SITE_URL = "https://windmc.su";
+/**
+ * Генерирует пару PKCE (code_verifier + code_challenge, метод S256).
+ * Используйте для публичных клиентов (SPA, мобильные приложения), у которых
+ * нет безопасного места для хранения clientSecret: code_verifier храните
+ * у себя (например, в сессии) до обмена кода на токен, code_challenge —
+ * передайте в {@link WindClient.getAuthorizeUrl}.
+ */
+export function generatePKCE() {
+    const codeVerifier = crypto.randomBytes(32).toString("base64url");
+    const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
+    return { codeVerifier, codeChallenge };
+}
+export class WindClient {
+    constructor(config) {
+        this.config = {
+            clientId: config.clientId,
+            clientSecret: config.clientSecret ?? "",
+            redirectUri: config.redirectUri ?? "",
+            appToken: config.appToken ?? "",
+            webhookSecret: config.webhookSecret ?? "",
+            apiUrl: config.apiUrl ?? DEFAULT_API_URL,
+            siteUrl: config.siteUrl ?? DEFAULT_SITE_URL,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // OAuth
+    // ---------------------------------------------------------------------------
+    /**
+     * Возвращает URL для авторизации пользователя.
+     * @param scopes        - массив запрашиваемых scopes
+     * @param state         - произвольная строка для защиты от CSRF
+     * @param codeChallenge - PKCE code_challenge (см. {@link generatePKCE}); нужен для публичных
+     *                        клиентов (SPA, мобильные приложения), у которых нет clientSecret
+     */
+    getAuthorizeUrl(scopes, state, codeChallenge) {
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            response_type: "code",
+            scope: scopes.join(" "),
+        });
+        if (state)
+            params.set("state", state);
+        if (codeChallenge) {
+            params.set("code_challenge", codeChallenge);
+            params.set("code_challenge_method", "S256");
+        }
+        return `${this.config.siteUrl}/oauth2/authorize?${params.toString()}`;
+    }
+    /**
+     * Обменивает authorization code на токены.
+     * @param code         - код из redirect_uri
+     * @param codeVerifier - PKCE code_verifier, если авторизация запускалась с codeChallenge
+     */
+    async exchangeCode(code, codeVerifier) {
+        const params = {
+            grant_type: "authorization_code",
+            code,
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+        };
+        if (this.config.clientSecret)
+            params.client_secret = this.config.clientSecret;
+        if (codeVerifier)
+            params.code_verifier = codeVerifier;
+        return this.request("/api/oauth2/token", {
+            method: "POST",
+            body: new URLSearchParams(params),
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        });
+    }
+    /**
+     * Обновляет access token с помощью refresh token.
+     * Для PKCE-токенов (публичный клиент без clientSecret) секрет не требуется.
+     */
+    async refreshToken(refreshToken) {
+        const params = {
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: this.config.clientId,
+        };
+        if (this.config.clientSecret)
+            params.client_secret = this.config.clientSecret;
+        return this.request("/api/oauth2/token", {
+            method: "POST",
+            body: new URLSearchParams(params),
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        });
+    }
+    /**
+     * Отзывает токен.
+     * Для PKCE-токенов (публичный клиент без clientSecret) секрет не требуется.
+     */
+    async revokeToken(token) {
+        const params = {
+            token,
+            client_id: this.config.clientId,
+        };
+        if (this.config.clientSecret)
+            params.client_secret = this.config.clientSecret;
+        await this.request("/api/oauth2/revoke", {
+            method: "POST",
+            body: new URLSearchParams(params),
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // @me (OAuth user endpoints)
+    // ---------------------------------------------------------------------------
+    /**
+     * Возвращает информацию о текущем пользователе.
+     * Требует scope: identify
+     */
+    async getUser(accessToken) {
+        return this.request("/api/oauth2/@me", {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    }
+    /**
+     * Возвращает банковские счета пользователя.
+     * Требует scope: bank
+     */
+    async getBank(accessToken) {
+        return this.request("/api/oauth2/@me/bank", {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    }
+    /**
+     * Возвращает транзакции пользователя.
+     * Требует scope: bank
+     */
+    async getBankTransactions(accessToken, limit) {
+        const query = limit ? `?limit=${limit}` : "";
+        return this.request(`/api/oauth2/@me/bank/transactions${query}`, { headers: { Authorization: `Bearer ${accessToken}` } });
+    }
+    /**
+     * Возвращает сообщества пользователя.
+     * Требует scope: communities
+     */
+    async getCommunities(accessToken) {
+        return this.request("/api/oauth2/@me/communities", {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    }
+    /**
+     * Возвращает список друзей пользователя.
+     * Требует scope: friends
+     */
+    async getFriends(accessToken) {
+        return this.request("/api/oauth2/@me/friends", {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    }
+    /**
+     * Создаёт запрос на списание средств.
+     * Требует scope: bank:charge
+     */
+    async createCharge(accessToken, payload) {
+        return this.request("/api/oauth2/@me/bank/charge", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    /**
+     * Возвращает статус запроса на списание.
+     * Требует scope: bank:charge
+     */
+    async getCharge(accessToken, chargeId) {
+        return this.request(`/api/oauth2/@me/bank/charge/${chargeId}`, { headers: { Authorization: `Bearer ${accessToken}` } });
+    }
+    // ---------------------------------------------------------------------------
+    // Billing (app token auth)
+    // ---------------------------------------------------------------------------
+    /**
+     * Создаёт счёт на оплату. Использует App Token (X-Client-Id + Bearer).
+     * После создания пользователь перейдёт по payUrl для оплаты.
+     */
+    async createBill(payload) {
+        if (!this.config.appToken) {
+            throw new WindError("appToken не указан в конфигурации");
+        }
+        return this.request("/api/oauth2/billing/create", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Client-Id": this.config.clientId,
+                Authorization: `Bearer ${this.config.appToken}`,
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    /**
+     * Возвращает информацию о счёте по его ID.
+     */
+    async getBill(billId) {
+        return this.request(`/api/oauth2/billing/${billId}`);
+    }
+    // ---------------------------------------------------------------------------
+    // Webhooks
+    // ---------------------------------------------------------------------------
+    /**
+     * Проверяет подпись входящего вебхука.
+     * @param rawBody   - тело запроса как строка (до JSON.parse)
+     * @param signature - значение заголовка X-Signature
+     */
+    verifyWebhookSignature(rawBody, signature) {
+        if (!this.config.webhookSecret) {
+            throw new WindError("webhookSecret не указан в конфигурации");
+        }
+        const expected = "sha256=" +
+            crypto
+                .createHmac("sha256", this.config.webhookSecret)
+                .update(rawBody)
+                .digest("hex");
+        if (expected.length !== signature.length)
+            return false;
+        return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+    }
+    /**
+     * Парсит тело вебхука с проверкой подписи.
+     * Бросает WindError если подпись неверна.
+     */
+    parseWebhook(rawBody, signature) {
+        if (!this.verifyWebhookSignature(rawBody, signature)) {
+            throw new WindError("Неверная подпись вебхука", 401);
+        }
+        return JSON.parse(rawBody);
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    async request(path, init = {}) {
+        const url = `${this.config.apiUrl}${path}`;
+        const res = await fetch(url, init);
+        let data;
+        const contentType = res.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            data = await res.json();
+        }
+        else {
+            data = await res.text();
+        }
+        if (!res.ok) {
+            const message = typeof data === "object" &&
+                data !== null &&
+                "error" in data &&
+                typeof data.error === "string"
+                ? data.error
+                : `HTTP ${res.status}`;
+            throw new WindError(message, res.status, typeof data === "object" ? data : undefined);
+        }
+        return data;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,125 @@
+export interface Config {
+    clientId: string;
+    clientSecret?: string;
+    redirectUri?: string;
+    appToken?: string;
+    webhookSecret?: string;
+    apiUrl?: string;
+    siteUrl?: string;
+}
+export interface AccessTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+    scope: string;
+}
+export type WindScope = "identify" | "bank" | "bank:charge" | "communities" | "friends";
+export interface User {
+    discordId: string;
+    nickname: string | null;
+    uuid: string | null;
+    discordUsername: string | null;
+    roles: string[];
+    online: boolean;
+    avatar: string | null;
+}
+export interface BankAccount {
+    id: number;
+    name: string;
+    balance: number;
+    frozen: boolean;
+    design: string | null;
+}
+export interface BankResponse {
+    accounts: BankAccount[];
+    totalBalance: number;
+}
+export interface Transaction {
+    id: string | number;
+    fromAccountId: number;
+    toAccountId: number;
+    amount: number;
+    type: string;
+    comment: string | null;
+    timestamp: string;
+}
+export interface TransactionsResponse {
+    transactions: Transaction[];
+    count: number;
+}
+export interface Community {
+    id: string;
+    name: string;
+    slug: string;
+    banner: string | null;
+    description: string | null;
+    memberCount: number;
+    verified: boolean;
+    role: "owner" | "co_owner" | "member";
+}
+export interface CommunitiesResponse {
+    communities: Community[];
+}
+export interface FriendUser {
+    id: string;
+    nickname: string | null;
+    uuid: string | null;
+    discordUsername: string | null;
+}
+export interface Friend {
+    friendshipId: string;
+    user: FriendUser;
+    since: string;
+}
+export interface FriendsResponse {
+    friends: Friend[];
+}
+export interface ChargeRequest {
+    chargeId: string;
+    status: "pending" | "paid" | "expired";
+    amount?: number;
+    fromAccountId?: number;
+    toAccountId?: number;
+}
+export interface CreateChargePayload {
+    amount: number;
+    toAccountId: number;
+    fromAccountId?: number;
+    comment?: string;
+}
+export interface CreateBillPayload {
+    toAccountId: number;
+    amount: number;
+    comment?: string;
+    webhookUrl?: string;
+    returnUrl?: string;
+}
+export interface CreateBillResponse {
+    billId: string;
+    payUrl: string;
+    expiresAt: string;
+}
+export interface BillApp {
+    name: string;
+    iconUrl: string | null;
+}
+export interface BillStatusResponse {
+    billId: string;
+    status: "pending" | "paid" | "expired";
+    amount: number;
+    comment: string | null;
+    toAccountId: number;
+    returnUrl: string | null;
+    expiresAt: string;
+    app: BillApp;
+}
+export interface WebhookPayload {
+    event: "bill.paid";
+    billId: string;
+    amount: number;
+    fromAccountId: number;
+    toAccountId: number;
+    payerId: string;
+    timestamp: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// WindClient types © Винд 2026
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@windmc/js",
+  "version": "1.0.0",
+  "description": "Wind API client",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.6.0",
+    "express": "^5.2.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}