Версия 0.1.3 · Команды установки используют точные версии.

Node.js / TypeScript SDK для Telegram Stars и Premium

Установка независимого SDK Fragment Donor для Node.js / TypeScript: username, подарки Stars/Premium и rate limit.

При покупке mnemonic кошелька и сессия/cookie Fragment передаются оператору API.

Runtime: Node.js 20+. Устанавливайте пакет из реестра только после статуса PUBLISHED; до этого используйте сборку каталога typescript из public source.

Клиент предлагает username, покупку Stars, подарок Premium и баланс с naming, принятым в Node.js / TypeScript. Запросы используют form-urlencoded. Баланс сохраняется decimal-строкой, дополнительные поля не удаляются.

Настройте timeout и данные кошелька на backend. Повтор чтения включается явно и ограничен; покупки никогда не повторяются автоматически. Точный constructor и типы ошибок приведены в README пакета.

Установка

npm install fragment-donor-sdk@0.1.3

Пример

// Trusted server example. Opt in and choose exactly one purchase kind.
import {
  ApiError,
  FloodWaitError,
  FragmentDonorClient,
  WalletCredentials,
} from "fragment-donor-sdk";

const allowPurchase = process.env.FRAGMENT_ALLOW_PURCHASES === "yes";
const purchaseKind = process.env.FRAGMENT_PURCHASE_KIND;
if (allowPurchase && !["stars", "premium"].includes(purchaseKind)) {
  throw new Error(
    "Set FRAGMENT_PURCHASE_KIND=stars or premium; no purchase sent",
  );
}
const client = new FragmentDonorClient();
const username = process.env.FRAGMENT_USERNAME ?? "durov";
try {
  console.log("Username:", (await client.getUserInfo(username)).username);
  if (process.env.FRAGMENT_MNEMONIC) {
    const credentials = new WalletCredentials({
      mnemonic: process.env.FRAGMENT_MNEMONIC,
      cookie: process.env.FRAGMENT_COOKIE,
      providerKey: process.env.TONCONSOLE_API_KEY,
    });
    const balance = await client.walletBalance({ credentials });
    console.log("TON:", balance.ton, "USDT:", balance.usdt_ton);
    if (allowPurchase && purchaseKind === "stars") {
      // One intentional operation; NEVER retry automatically.
      await client.buyStars(username, 50, { credentials });
    } else if (allowPurchase && purchaseKind === "premium") {
      await client.buyPremium(username, 3, { credentials });
    }
  }
} catch (error) {
  if (error instanceof FloodWaitError)
    console.log("FLOOD_WAIT seconds:", error.retryAfter);
  else if (error instanceof ApiError)
    console.log(
      error.name,
      error.status,
      "unknown purchase outcome:",
      error.purchaseOutcomeUnknown,
    );
  else throw error;
}

Исходный код · typescript

Читайте дальше

Telegram Stars API: 429, Retry-After и flood wait · Защита данных кошелька при интеграции API · Вопросы об API и SDK Fragment Donor

OpenAPI 3.0 · Postman collection