@rngrow/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RnG - Recruit n' Grow (rngrow.com)
+
+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,100 @@
+# rngrow
+
+Official SDK for the [RnG TikTok LIVE Creator API](https://rngrow.com/api-docs).
+
+Pull TikTok LIVE creator data straight into your own tools: recruitable creators verified by
+RnG's checker pipeline, LIVE league boards, gaming and daily rankings, and real-time HOT
+signals for creators spiking in diamonds right now.
+
+- Typed responses, zero dependencies, Node.js 18+
+- Automatic cursor pagination for the creators pool
+- Clear, machine-readable errors with rate-limit awareness
+
+API access is included with the [Radar plan](https://rngrow.com/pricing). Generate your key
+in [Dashboard → API Access](https://rngrow.com/dashboard/api).
+
+## Install
+
+```bash
+npm install rngrow
+```
+
+## Quickstart
+
+```ts
+import { Rngrow } from "rngrow";
+
+const rng = new Rngrow(process.env.RNG_API_KEY!);
+
+// Who am I? Countries, limits, usage.
+console.log(await rng.me());
+
+// One page of recruitable creators, newest checked first
+const page = await rng.creators.list({ country: "RO", limit: 100 });
+for (const c of page.creators) {
+  console.log(c.username, c.follower_count, c.checked_at);
+}
+
+// Walk the whole pool with automatic pagination
+for await (const creator of rng.creators.iterate({ country: "RO", maxItems: 1000 })) {
+  console.log(creator.username);
+}
+```
+
+## League data
+
+```ts
+// Which divisions exist for your countries
+const coverage = await rng.leagues.list();
+
+// A division's full ranked board (top 99) with recruitability + HOT status
+const board = await rng.leagues.board({ country: "RO", division: "A1" });
+
+// Only the recruitable creators across all of a country's boards
+const recruitable = await rng.leagues.available({ country: "RO", limit: 200 });
+
+// Gaming and daily rankings
+const games = await rng.leagues.games({ country: "US" });
+const gaming = await rng.leagues.gaming({ country: "US", game: "all" });
+const daily = await rng.leagues.daily({ country: "RO" });
+
+// Creators spiking RIGHT NOW
+const hot = await rng.leagues.hot({ country: "RO" });
+```
+
+## Errors
+
+Every failure throws a `RngrowError` with a stable `code`, the HTTP `status`, and
+`retryAfter` (seconds) when rate limited:
+
+```ts
+import { Rngrow, RngrowError } from "rngrow";
+
+try {
+  await rng.creators.list({ country: "US" });
+} catch (e) {
+  if (e instanceof RngrowError) {
+    // e.code: missing_api_key | invalid_api_key | plan_required |
+    //         country_not_in_plan | invalid_request | not_found |
+    //         rate_limited | server_error
+    if (e.code === "rate_limited") {
+      console.log(`Backing off ${e.retryAfter ?? 60}s`);
+    }
+  }
+}
+```
+
+## Rate limits
+
+60 requests per minute and 10,000 per day per key. Responses carry
+`X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Use
+`since` and cursors to poll efficiently instead of re-downloading the pool.
+
+## Links
+
+- [API documentation](https://rngrow.com/api-docs)
+- [Pricing](https://rngrow.com/pricing)
+- Support: support@rngrow.com
+
+RnG is an independent data platform and is not affiliated with, endorsed by, or sponsored by
+TikTok or ByteDance.

package/dist/index.cjs

@@ -0,0 +1,150 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Rngrow: () => Rngrow,
+  RngrowError: () => RngrowError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://rngrow.com/api/v1";
+var RngrowError = class extends Error {
+  constructor(code, message, status, retryAfter) {
+    super(message);
+    this.name = "RngrowError";
+    this.code = code;
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+};
+var Rngrow = class {
+  constructor(apiKey, options = {}) {
+    this.creators = {
+      /**
+       * One page of the available-creators pool, newest checked first.
+       * Paginate by passing next_cursor back as cursor.
+       */
+      list: (params) => this.request("/creators", {
+        country: params.country,
+        limit: params.limit,
+        cursor: params.cursor,
+        since: params.since instanceof Date ? params.since.toISOString() : params.since,
+        include_diamonds: params.includeDiamonds ? "true" : void 0
+      }),
+      /** Discovery volume for a country. */
+      stats: (params) => this.request("/creators/stats", { country: params.country }),
+      /**
+       * Iterate the whole pool with automatic cursor pagination.
+       *
+       *   for await (const creator of rng.creators.iterate({ country: "RO" })) { … }
+       */
+      iterate: (params) => {
+        const self = this;
+        async function* gen() {
+          let cursor;
+          let yielded = 0;
+          for (; ; ) {
+            const page = await self.creators.list({
+              country: params.country,
+              since: params.since,
+              includeDiamonds: params.includeDiamonds,
+              limit: 200,
+              cursor
+            });
+            for (const c of page.creators) {
+              yield c;
+              yielded++;
+              if (params.maxItems && yielded >= params.maxItems) return;
+            }
+            if (!page.has_more || !page.next_cursor) return;
+            cursor = page.next_cursor;
+          }
+        }
+        return gen();
+      }
+    };
+    this.leagues = {
+      /** Division coverage for every country on your plan. */
+      list: () => this.request("/leagues"),
+      /** One division's full ranked board (top 99), with recruitability + HOT status. */
+      board: (params) => this.request("/leagues/board", params),
+      /** Only the recruitable creators across a country's league boards. */
+      available: (params) => this.request("/leagues/available", params),
+      /** A country's gaming ranking, combined ("all") or per game slug. */
+      gaming: (params) => this.request("/leagues/gaming", params),
+      /** Which per-game boards exist for a country. */
+      games: (params) => this.request("/leagues/gaming/games", params),
+      /** The country's daily (hourly for MENA) diamond ranking. */
+      daily: (params) => this.request("/leagues/daily", params),
+      /** Creators spiking in diamonds right now, across all divisions. */
+      hot: (params) => this.request("/leagues/hot", params)
+    };
+    if (!apiKey || !apiKey.startsWith("rng_")) {
+      throw new Error(
+        "Rngrow: an API key starting with rng_ is required. Generate one at https://rngrow.com/dashboard/api"
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const f = options.fetch ?? globalThis.fetch;
+    if (!f) {
+      throw new Error("Rngrow: global fetch not found (Node 18+ required) and no fetch option given.");
+    }
+    this.fetchImpl = f.bind(globalThis);
+  }
+  async request(path, query = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0 && v !== null && v !== "") url.searchParams.set(k, String(v));
+    }
+    const res = await this.fetchImpl(url.toString(), {
+      headers: { "X-API-Key": this.apiKey, Accept: "application/json" }
+    });
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      body = void 0;
+    }
+    if (!res.ok) {
+      const err = body?.error;
+      const retryHeader = res.headers.get("Retry-After");
+      const retryAfter = retryHeader ? Number(retryHeader) || void 0 : void 0;
+      throw new RngrowError(
+        err?.code ?? "server_error",
+        err?.message ?? `Request failed with HTTP ${res.status}`,
+        res.status,
+        retryAfter
+      );
+    }
+    return body;
+  }
+  /** Key introspection: plan, countries, rate limits, usage today. */
+  me() {
+    return this.request("/me");
+  }
+};
+var index_default = Rngrow;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Rngrow,
+  RngrowError
+});

package/dist/index.d.cts

@@ -0,0 +1,241 @@
+/**
+ * Official SDK for the RnG TikTok LIVE Creator API.
+ *
+ *   npm install rngrow
+ *
+ *   import { Rngrow } from "rngrow";
+ *   const rng = new Rngrow(process.env.RNG_API_KEY!);
+ *   const page = await rng.creators.list({ country: "RO" });
+ *
+ * Docs: https://rngrow.com/api-docs
+ * API access is included with the Radar plan; generate a key at
+ * https://rngrow.com/dashboard/api.
+ */
+interface Me {
+    key: {
+        name: string;
+        prefix: string;
+        created_at: string;
+    };
+    plan: "radar" | "admin";
+    countries: string[] | "all";
+    rate_limit: {
+        per_minute: number;
+        per_day: number;
+    };
+    usage_today: number;
+}
+interface Creator {
+    id: number | string;
+    username: string;
+    display_name: string | null;
+    invitation_type: string | null;
+    checked_at: string | null;
+    viewer_count: string | number | null;
+    follower_count: number | null;
+    /** Present only when include_diamonds was requested. */
+    diamonds?: number | null;
+}
+interface CreatorsPage {
+    country: string;
+    count: number;
+    /** Present only on the first page (no cursor). */
+    total?: number;
+    has_more: boolean;
+    next_cursor: string | null;
+    creators: Creator[];
+}
+interface CreatorStats {
+    country: string;
+    total_scraped: number;
+    available_now: number;
+    last_30_days: number;
+    last_24_hours: number;
+}
+interface LeagueDivision {
+    division: string;
+    captured_at: string | null;
+    board_age_minutes: number | null;
+}
+interface LeagueCoverage {
+    countries: {
+        country: string;
+        divisions: LeagueDivision[];
+    }[];
+}
+interface LeagueBoardRow {
+    rank: number;
+    username: string | null;
+    nickname: string | null;
+    score: number | null;
+    follower_count: number | null;
+    league_letter: string | null;
+    was_live: boolean | null;
+    recruit_status: "available" | "contacted" | "not_available" | "unknown" | string;
+    check_age_minutes: number | null;
+    hot_status: "none" | "hot" | "diamond" | string;
+}
+interface LeagueBoard {
+    country: string;
+    division: string;
+    board_age_minutes: number | null;
+    count: number;
+    rows: LeagueBoardRow[];
+}
+interface LeagueAvailableCreator {
+    division: string;
+    rank: number;
+    username: string | null;
+    nickname: string | null;
+    score: number | null;
+    follower_count: number | null;
+    league_letter: string | null;
+    check_age_minutes: number | null;
+}
+interface LeagueAvailablePage {
+    country: string;
+    division?: string;
+    total: number;
+    limit: number;
+    offset: number;
+    count: number;
+    creators: LeagueAvailableCreator[];
+}
+interface RankingRow {
+    rank: number;
+    username: string | null;
+    nickname: string | null;
+    diamonds: number | null;
+    follower_count: number | null;
+    was_live: boolean | null;
+    recruit_status: string;
+    check_age_minutes: number | null;
+    creator_country: string | null;
+    /** Gaming board only: creator's tracked country equals the board's country. */
+    is_home?: boolean;
+}
+interface GamingBoard {
+    country: string;
+    game: string;
+    board_age_minutes: number | null;
+    count: number;
+    rows: RankingRow[];
+}
+interface DailyBoard {
+    country: string;
+    board_type: "daily" | "hourly" | string;
+    board_age_minutes: number | null;
+    count: number;
+    rows: RankingRow[];
+}
+interface GamingGame {
+    game: string;
+    label: string;
+    captured_at: string | null;
+}
+interface HotCreator {
+    division: string;
+    username: string | null;
+    nickname: string | null;
+    status: "hot" | "diamond" | string;
+    diamonds_gained: number | null;
+    score: number | null;
+    follower_count: number | null;
+    hot_since: string | null;
+}
+interface HotCreators {
+    country: string;
+    count: number;
+    creators: HotCreator[];
+}
+declare class RngrowError extends Error {
+    /** Machine-readable error code, e.g. "country_not_in_plan" or "rate_limited". */
+    readonly code: string;
+    /** HTTP status of the failed response. */
+    readonly status: number;
+    /** Seconds to wait before retrying (rate_limited only). */
+    readonly retryAfter?: number;
+    constructor(code: string, message: string, status: number, retryAfter?: number);
+}
+interface RngrowOptions {
+    /** Override the API base URL. Default: https://rngrow.com/api/v1 */
+    baseUrl?: string;
+    /** Custom fetch implementation (default: globalThis.fetch, Node 18+). */
+    fetch?: typeof globalThis.fetch;
+}
+declare class Rngrow {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(apiKey: string, options?: RngrowOptions);
+    private request;
+    /** Key introspection: plan, countries, rate limits, usage today. */
+    me(): Promise<Me>;
+    readonly creators: {
+        /**
+         * One page of the available-creators pool, newest checked first.
+         * Paginate by passing next_cursor back as cursor.
+         */
+        list: (params: {
+            country: string;
+            limit?: number;
+            cursor?: string;
+            since?: string | Date;
+            includeDiamonds?: boolean;
+        }) => Promise<CreatorsPage>;
+        /** Discovery volume for a country. */
+        stats: (params: {
+            country: string;
+        }) => Promise<CreatorStats>;
+        /**
+         * Iterate the whole pool with automatic cursor pagination.
+         *
+         *   for await (const creator of rng.creators.iterate({ country: "RO" })) { … }
+         */
+        iterate: (params: {
+            country: string;
+            since?: string | Date;
+            includeDiamonds?: boolean;
+            /** Stop after this many creators (default: no limit). */
+            maxItems?: number;
+        }) => AsyncGenerator<Creator, void, undefined>;
+    };
+    readonly leagues: {
+        /** Division coverage for every country on your plan. */
+        list: () => Promise<LeagueCoverage>;
+        /** One division's full ranked board (top 99), with recruitability + HOT status. */
+        board: (params: {
+            country: string;
+            division: string;
+        }) => Promise<LeagueBoard>;
+        /** Only the recruitable creators across a country's league boards. */
+        available: (params: {
+            country: string;
+            division?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<LeagueAvailablePage>;
+        /** A country's gaming ranking, combined ("all") or per game slug. */
+        gaming: (params: {
+            country: string;
+            game?: string;
+        }) => Promise<GamingBoard>;
+        /** Which per-game boards exist for a country. */
+        games: (params: {
+            country: string;
+        }) => Promise<{
+            country: string;
+            games: GamingGame[];
+        }>;
+        /** The country's daily (hourly for MENA) diamond ranking. */
+        daily: (params: {
+            country: string;
+        }) => Promise<DailyBoard>;
+        /** Creators spiking in diamonds right now, across all divisions. */
+        hot: (params: {
+            country: string;
+        }) => Promise<HotCreators>;
+    };
+}
+
+export { type Creator, type CreatorStats, type CreatorsPage, type DailyBoard, type GamingBoard, type GamingGame, type HotCreator, type HotCreators, type LeagueAvailableCreator, type LeagueAvailablePage, type LeagueBoard, type LeagueBoardRow, type LeagueCoverage, type LeagueDivision, type Me, type RankingRow, Rngrow, RngrowError, type RngrowOptions, Rngrow as default };

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Official SDK for the RnG TikTok LIVE Creator API.
+ *
+ *   npm install rngrow
+ *
+ *   import { Rngrow } from "rngrow";
+ *   const rng = new Rngrow(process.env.RNG_API_KEY!);
+ *   const page = await rng.creators.list({ country: "RO" });
+ *
+ * Docs: https://rngrow.com/api-docs
+ * API access is included with the Radar plan; generate a key at
+ * https://rngrow.com/dashboard/api.
+ */
+interface Me {
+    key: {
+        name: string;
+        prefix: string;
+        created_at: string;
+    };
+    plan: "radar" | "admin";
+    countries: string[] | "all";
+    rate_limit: {
+        per_minute: number;
+        per_day: number;
+    };
+    usage_today: number;
+}
+interface Creator {
+    id: number | string;
+    username: string;
+    display_name: string | null;
+    invitation_type: string | null;
+    checked_at: string | null;
+    viewer_count: string | number | null;
+    follower_count: number | null;
+    /** Present only when include_diamonds was requested. */
+    diamonds?: number | null;
+}
+interface CreatorsPage {
+    country: string;
+    count: number;
+    /** Present only on the first page (no cursor). */
+    total?: number;
+    has_more: boolean;
+    next_cursor: string | null;
+    creators: Creator[];
+}
+interface CreatorStats {
+    country: string;
+    total_scraped: number;
+    available_now: number;
+    last_30_days: number;
+    last_24_hours: number;
+}
+interface LeagueDivision {
+    division: string;
+    captured_at: string | null;
+    board_age_minutes: number | null;
+}
+interface LeagueCoverage {
+    countries: {
+        country: string;
+        divisions: LeagueDivision[];
+    }[];
+}
+interface LeagueBoardRow {
+    rank: number;
+    username: string | null;
+    nickname: string | null;
+    score: number | null;
+    follower_count: number | null;
+    league_letter: string | null;
+    was_live: boolean | null;
+    recruit_status: "available" | "contacted" | "not_available" | "unknown" | string;
+    check_age_minutes: number | null;
+    hot_status: "none" | "hot" | "diamond" | string;
+}
+interface LeagueBoard {
+    country: string;
+    division: string;
+    board_age_minutes: number | null;
+    count: number;
+    rows: LeagueBoardRow[];
+}
+interface LeagueAvailableCreator {
+    division: string;
+    rank: number;
+    username: string | null;
+    nickname: string | null;
+    score: number | null;
+    follower_count: number | null;
+    league_letter: string | null;
+    check_age_minutes: number | null;
+}
+interface LeagueAvailablePage {
+    country: string;
+    division?: string;
+    total: number;
+    limit: number;
+    offset: number;
+    count: number;
+    creators: LeagueAvailableCreator[];
+}
+interface RankingRow {
+    rank: number;
+    username: string | null;
+    nickname: string | null;
+    diamonds: number | null;
+    follower_count: number | null;
+    was_live: boolean | null;
+    recruit_status: string;
+    check_age_minutes: number | null;
+    creator_country: string | null;
+    /** Gaming board only: creator's tracked country equals the board's country. */
+    is_home?: boolean;
+}
+interface GamingBoard {
+    country: string;
+    game: string;
+    board_age_minutes: number | null;
+    count: number;
+    rows: RankingRow[];
+}
+interface DailyBoard {
+    country: string;
+    board_type: "daily" | "hourly" | string;
+    board_age_minutes: number | null;
+    count: number;
+    rows: RankingRow[];
+}
+interface GamingGame {
+    game: string;
+    label: string;
+    captured_at: string | null;
+}
+interface HotCreator {
+    division: string;
+    username: string | null;
+    nickname: string | null;
+    status: "hot" | "diamond" | string;
+    diamonds_gained: number | null;
+    score: number | null;
+    follower_count: number | null;
+    hot_since: string | null;
+}
+interface HotCreators {
+    country: string;
+    count: number;
+    creators: HotCreator[];
+}
+declare class RngrowError extends Error {
+    /** Machine-readable error code, e.g. "country_not_in_plan" or "rate_limited". */
+    readonly code: string;
+    /** HTTP status of the failed response. */
+    readonly status: number;
+    /** Seconds to wait before retrying (rate_limited only). */
+    readonly retryAfter?: number;
+    constructor(code: string, message: string, status: number, retryAfter?: number);
+}
+interface RngrowOptions {
+    /** Override the API base URL. Default: https://rngrow.com/api/v1 */
+    baseUrl?: string;
+    /** Custom fetch implementation (default: globalThis.fetch, Node 18+). */
+    fetch?: typeof globalThis.fetch;
+}
+declare class Rngrow {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(apiKey: string, options?: RngrowOptions);
+    private request;
+    /** Key introspection: plan, countries, rate limits, usage today. */
+    me(): Promise<Me>;
+    readonly creators: {
+        /**
+         * One page of the available-creators pool, newest checked first.
+         * Paginate by passing next_cursor back as cursor.
+         */
+        list: (params: {
+            country: string;
+            limit?: number;
+            cursor?: string;
+            since?: string | Date;
+            includeDiamonds?: boolean;
+        }) => Promise<CreatorsPage>;
+        /** Discovery volume for a country. */
+        stats: (params: {
+            country: string;
+        }) => Promise<CreatorStats>;
+        /**
+         * Iterate the whole pool with automatic cursor pagination.
+         *
+         *   for await (const creator of rng.creators.iterate({ country: "RO" })) { … }
+         */
+        iterate: (params: {
+            country: string;
+            since?: string | Date;
+            includeDiamonds?: boolean;
+            /** Stop after this many creators (default: no limit). */
+            maxItems?: number;
+        }) => AsyncGenerator<Creator, void, undefined>;
+    };
+    readonly leagues: {
+        /** Division coverage for every country on your plan. */
+        list: () => Promise<LeagueCoverage>;
+        /** One division's full ranked board (top 99), with recruitability + HOT status. */
+        board: (params: {
+            country: string;
+            division: string;
+        }) => Promise<LeagueBoard>;
+        /** Only the recruitable creators across a country's league boards. */
+        available: (params: {
+            country: string;
+            division?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<LeagueAvailablePage>;
+        /** A country's gaming ranking, combined ("all") or per game slug. */
+        gaming: (params: {
+            country: string;
+            game?: string;
+        }) => Promise<GamingBoard>;
+        /** Which per-game boards exist for a country. */
+        games: (params: {
+            country: string;
+        }) => Promise<{
+            country: string;
+            games: GamingGame[];
+        }>;
+        /** The country's daily (hourly for MENA) diamond ranking. */
+        daily: (params: {
+            country: string;
+        }) => Promise<DailyBoard>;
+        /** Creators spiking in diamonds right now, across all divisions. */
+        hot: (params: {
+            country: string;
+        }) => Promise<HotCreators>;
+    };
+}
+
+export { type Creator, type CreatorStats, type CreatorsPage, type DailyBoard, type GamingBoard, type GamingGame, type HotCreator, type HotCreators, type LeagueAvailableCreator, type LeagueAvailablePage, type LeagueBoard, type LeagueBoardRow, type LeagueCoverage, type LeagueDivision, type Me, type RankingRow, Rngrow, RngrowError, type RngrowOptions, Rngrow as default };

package/dist/index.js

@@ -0,0 +1,124 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://rngrow.com/api/v1";
+var RngrowError = class extends Error {
+  constructor(code, message, status, retryAfter) {
+    super(message);
+    this.name = "RngrowError";
+    this.code = code;
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+};
+var Rngrow = class {
+  constructor(apiKey, options = {}) {
+    this.creators = {
+      /**
+       * One page of the available-creators pool, newest checked first.
+       * Paginate by passing next_cursor back as cursor.
+       */
+      list: (params) => this.request("/creators", {
+        country: params.country,
+        limit: params.limit,
+        cursor: params.cursor,
+        since: params.since instanceof Date ? params.since.toISOString() : params.since,
+        include_diamonds: params.includeDiamonds ? "true" : void 0
+      }),
+      /** Discovery volume for a country. */
+      stats: (params) => this.request("/creators/stats", { country: params.country }),
+      /**
+       * Iterate the whole pool with automatic cursor pagination.
+       *
+       *   for await (const creator of rng.creators.iterate({ country: "RO" })) { … }
+       */
+      iterate: (params) => {
+        const self = this;
+        async function* gen() {
+          let cursor;
+          let yielded = 0;
+          for (; ; ) {
+            const page = await self.creators.list({
+              country: params.country,
+              since: params.since,
+              includeDiamonds: params.includeDiamonds,
+              limit: 200,
+              cursor
+            });
+            for (const c of page.creators) {
+              yield c;
+              yielded++;
+              if (params.maxItems && yielded >= params.maxItems) return;
+            }
+            if (!page.has_more || !page.next_cursor) return;
+            cursor = page.next_cursor;
+          }
+        }
+        return gen();
+      }
+    };
+    this.leagues = {
+      /** Division coverage for every country on your plan. */
+      list: () => this.request("/leagues"),
+      /** One division's full ranked board (top 99), with recruitability + HOT status. */
+      board: (params) => this.request("/leagues/board", params),
+      /** Only the recruitable creators across a country's league boards. */
+      available: (params) => this.request("/leagues/available", params),
+      /** A country's gaming ranking, combined ("all") or per game slug. */
+      gaming: (params) => this.request("/leagues/gaming", params),
+      /** Which per-game boards exist for a country. */
+      games: (params) => this.request("/leagues/gaming/games", params),
+      /** The country's daily (hourly for MENA) diamond ranking. */
+      daily: (params) => this.request("/leagues/daily", params),
+      /** Creators spiking in diamonds right now, across all divisions. */
+      hot: (params) => this.request("/leagues/hot", params)
+    };
+    if (!apiKey || !apiKey.startsWith("rng_")) {
+      throw new Error(
+        "Rngrow: an API key starting with rng_ is required. Generate one at https://rngrow.com/dashboard/api"
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const f = options.fetch ?? globalThis.fetch;
+    if (!f) {
+      throw new Error("Rngrow: global fetch not found (Node 18+ required) and no fetch option given.");
+    }
+    this.fetchImpl = f.bind(globalThis);
+  }
+  async request(path, query = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0 && v !== null && v !== "") url.searchParams.set(k, String(v));
+    }
+    const res = await this.fetchImpl(url.toString(), {
+      headers: { "X-API-Key": this.apiKey, Accept: "application/json" }
+    });
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      body = void 0;
+    }
+    if (!res.ok) {
+      const err = body?.error;
+      const retryHeader = res.headers.get("Retry-After");
+      const retryAfter = retryHeader ? Number(retryHeader) || void 0 : void 0;
+      throw new RngrowError(
+        err?.code ?? "server_error",
+        err?.message ?? `Request failed with HTTP ${res.status}`,
+        res.status,
+        retryAfter
+      );
+    }
+    return body;
+  }
+  /** Key introspection: plan, countries, rate limits, usage today. */
+  me() {
+    return this.request("/me");
+  }
+};
+var index_default = Rngrow;
+export {
+  Rngrow,
+  RngrowError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@rngrow/sdk",
+  "version": "0.1.0",
+  "description": "Official SDK for the RnG TikTok LIVE Creator API (rngrow.com): recruitable TikTok creators, LIVE league boards, gaming and daily rankings, and real-time HOT signals.",
+  "keywords": [
+    "tiktok",
+    "tiktok-api",
+    "tiktok-live",
+    "tiktok-creators",
+    "creator-data",
+    "live-leagues",
+    "recruiting",
+    "rngrow"
+  ],
+  "homepage": "https://rngrow.com/api-docs",
+  "bugs": { "email": "support@rngrow.com" },
+  "license": "MIT",
+  "author": "RnG - Recruit n' Grow (https://rngrow.com)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.2.4",
+    "typescript": "^5.5.4"
+  }
+}