@rngrow/sdk 0.1.1 → 0.2.0

package/README.md

@@ -58,8 +58,29 @@ 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
+// Creators spiking RIGHT NOW, and their spike history
 const hot = await rng.leagues.hot({ country: "RO" });
+const history = await rng.leagues.hotHistory({ country: "RO", days: 7 });
+
+// Creators who fell off a board and are still recruitable (warm leads)
+const dropouts = await rng.leagues.dropouts({ country: "RO", division: "D1" });
+
+// Bulk export, JSON or CSV, up to 25,000 rows
+const bulk = await rng.leagues.export({ country: "RO" });
+const csv = await rng.leagues.exportCsv({ country: "RO", source: "gaming" });
+```
+
+## Gifters and live lookup
+
+```ts
+// The country's biggest gift senders (whales)
+const whales = await rng.gifters.list({ country: "RO", sort: "7d" });
+
+// Which creators one gifter funds, and for how much
+const detail = await rng.gifters.detail({ gifterId: whales.gifters[0].gifter_id });
+
+// Real-time TikTok lookup: does the handle exist, are they LIVE right now
+const who = await rng.creators.resolve({ username: "somehandle" });
 ```
 
 ## Errors

package/dist/index.cjs

@@ -51,6 +51,8 @@ var Rngrow = class {
       }),
       /** Discovery volume for a country. */
       stats: (params) => this.request("/creators/stats", { country: params.country }),
+      /** Resolve a TikTok handle in real time: profile + LIVE-right-now status. */
+      resolve: (params) => this.request("/creators/resolve", { username: params.username }),
       /**
        * Iterate the whole pool with automatic cursor pagination.
        *
@@ -95,7 +97,36 @@ var Rngrow = class {
       /** 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)
+      hot: (params) => this.request("/leagues/hot", params),
+      /** Past HOT / diamond spike events, up to 30 days back. */
+      hotHistory: (params) => this.request("/leagues/hot/history", params),
+      /** Creators who fell off a division's board and are still recruitable. */
+      dropouts: (params) => this.request("/leagues/dropouts", params),
+      /** Bulk board export as JSON, up to 25,000 rows. */
+      export: (params) => this.request("/leagues/export", {
+        country: params.country,
+        source: params.source,
+        divisions: params.divisions?.join(","),
+        games: params.games?.join(","),
+        available_only: params.availableOnly === false ? "false" : void 0,
+        max_score: params.maxScore
+      }),
+      /** Bulk board export as a ready-to-save CSV string. */
+      exportCsv: (params) => this.requestText("/leagues/export", {
+        country: params.country,
+        source: params.source,
+        divisions: params.divisions?.join(","),
+        games: params.games?.join(","),
+        available_only: params.availableOnly === false ? "false" : void 0,
+        max_score: params.maxScore,
+        format: "csv"
+      })
+    };
+    this.gifters = {
+      /** The country's top gift senders (whales), lifetime or rolling 7 days. */
+      list: (params) => this.request("/gifters", params),
+      /** One gifter's profile and exactly which creators they fund. */
+      detail: (params) => this.request(`/gifters/${encodeURIComponent(params.gifterId)}`)
     };
     if (!apiKey || !apiKey.startsWith("rng_")) {
       throw new Error(
@@ -137,6 +168,28 @@ var Rngrow = class {
     }
     return body;
   }
+  async requestText(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 }
+    });
+    if (!res.ok) {
+      let code = "server_error";
+      let message = `Request failed with HTTP ${res.status}`;
+      try {
+        const body = await res.json();
+        if (body?.error?.code) code = body.error.code;
+        if (body?.error?.message) message = body.error.message;
+      } catch {
+      }
+      const retryHeader = res.headers.get("Retry-After");
+      throw new RngrowError(code, message, res.status, retryHeader ? Number(retryHeader) || void 0 : void 0);
+    }
+    return res.text();
+  }
   /** Key introspection: plan, countries, rate limits, usage today. */
   me() {
     return this.request("/me");

package/dist/index.d.cts

@@ -148,6 +148,106 @@ interface HotCreators {
     count: number;
     creators: HotCreator[];
 }
+interface HotEvent {
+    division: string;
+    username: string | null;
+    status: "hot" | "diamond" | string;
+    score: number | null;
+    diamonds_gained: number | null;
+    captured_at: string | null;
+    tick_at: string;
+}
+interface HotHistoryPage {
+    country: string;
+    days: number;
+    division?: string;
+    username?: string;
+    total: number;
+    limit: number;
+    offset: number;
+    count: number;
+    events: HotEvent[];
+}
+interface Dropout {
+    best_rank: number | null;
+    best_score: number | null;
+    follower_count: number | null;
+    username: string;
+    nickname: string | null;
+    recruit_status: "available" | "contacted" | string;
+    check_age_minutes: number | null;
+    dropped_minutes_ago: number | null;
+}
+interface DropoutsResponse {
+    country: string;
+    division: string;
+    count: number;
+    dropouts: Dropout[];
+}
+interface ExportResponse {
+    country: string;
+    source: "league" | "gaming" | "daily";
+    count: number;
+    truncated: boolean;
+    rows: Record<string, unknown>[];
+}
+interface ResolvedCreator {
+    username: string;
+    nickname: string | null;
+    avatar: string | null;
+    verified: boolean;
+    follower_count: number | null;
+    live: boolean;
+}
+type ResolveResponse = {
+    found: true;
+    creator: ResolvedCreator;
+} | {
+    found: false;
+    username: string;
+};
+interface Gifter {
+    rank: number;
+    gifter_id: string;
+    username: string;
+    diamonds: number;
+    est_value_usd: number;
+    diamonds_7d: number | null;
+    creators_gifted: number | null;
+    gifts: number | null;
+    last_seen: string | null;
+}
+interface GiftersPage {
+    country: string;
+    sort: "lifetime" | "7d";
+    total_estimated: number | null;
+    limit: number;
+    offset: number;
+    count: number;
+    gifters: Gifter[];
+}
+interface GifterDetail {
+    gifter: {
+        gifter_id: string;
+        username: string;
+        country: string;
+        diamonds: number;
+        est_value_usd: number;
+        diamonds_7d: number | null;
+        diamonds_30d: number | null;
+        gifts: number | null;
+        creators_gifted: number | null;
+        first_seen: string | null;
+        last_seen: string | null;
+    };
+    creators: {
+        creator: string;
+        diamonds: number;
+        est_value_usd: number;
+        gifts: number | null;
+        last_gifted: string | null;
+    }[];
+}
 declare class RngrowError extends Error {
     /** Machine-readable error code, e.g. "country_not_in_plan" or "rate_limited". */
     readonly code: string;
@@ -169,6 +269,7 @@ declare class Rngrow {
     private readonly fetchImpl;
     constructor(apiKey: string, options?: RngrowOptions);
     private request;
+    private requestText;
     /** Key introspection: plan, countries, rate limits, usage today. */
     me(): Promise<Me>;
     readonly creators: {
@@ -187,6 +288,10 @@ declare class Rngrow {
         stats: (params: {
             country: string;
         }) => Promise<CreatorStats>;
+        /** Resolve a TikTok handle in real time: profile + LIVE-right-now status. */
+        resolve: (params: {
+            username: string;
+        }) => Promise<ResolveResponse>;
         /**
          * Iterate the whole pool with automatic cursor pagination.
          *
@@ -235,7 +340,52 @@ declare class Rngrow {
         hot: (params: {
             country: string;
         }) => Promise<HotCreators>;
+        /** Past HOT / diamond spike events, up to 30 days back. */
+        hotHistory: (params: {
+            country: string;
+            days?: number;
+            division?: string;
+            username?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<HotHistoryPage>;
+        /** Creators who fell off a division's board and are still recruitable. */
+        dropouts: (params: {
+            country: string;
+            division: string;
+        }) => Promise<DropoutsResponse>;
+        /** Bulk board export as JSON, up to 25,000 rows. */
+        export: (params: {
+            country: string;
+            source?: "league" | "gaming" | "daily";
+            divisions?: string[];
+            games?: string[];
+            availableOnly?: boolean;
+            maxScore?: number;
+        }) => Promise<ExportResponse>;
+        /** Bulk board export as a ready-to-save CSV string. */
+        exportCsv: (params: {
+            country: string;
+            source?: "league" | "gaming" | "daily";
+            divisions?: string[];
+            games?: string[];
+            availableOnly?: boolean;
+            maxScore?: number;
+        }) => Promise<string>;
+    };
+    readonly gifters: {
+        /** The country's top gift senders (whales), lifetime or rolling 7 days. */
+        list: (params: {
+            country: string;
+            sort?: "lifetime" | "7d";
+            limit?: number;
+            offset?: number;
+        }) => Promise<GiftersPage>;
+        /** One gifter's profile and exactly which creators they fund. */
+        detail: (params: {
+            gifterId: string;
+        }) => Promise<GifterDetail>;
     };
 }
 
-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 };
+export { type Creator, type CreatorStats, type CreatorsPage, type DailyBoard, type Dropout, type DropoutsResponse, type ExportResponse, type GamingBoard, type GamingGame, type Gifter, type GifterDetail, type GiftersPage, type HotCreator, type HotCreators, type HotEvent, type HotHistoryPage, type LeagueAvailableCreator, type LeagueAvailablePage, type LeagueBoard, type LeagueBoardRow, type LeagueCoverage, type LeagueDivision, type Me, type RankingRow, type ResolveResponse, type ResolvedCreator, Rngrow, RngrowError, type RngrowOptions, Rngrow as default };

package/dist/index.d.ts

@@ -148,6 +148,106 @@ interface HotCreators {
     count: number;
     creators: HotCreator[];
 }
+interface HotEvent {
+    division: string;
+    username: string | null;
+    status: "hot" | "diamond" | string;
+    score: number | null;
+    diamonds_gained: number | null;
+    captured_at: string | null;
+    tick_at: string;
+}
+interface HotHistoryPage {
+    country: string;
+    days: number;
+    division?: string;
+    username?: string;
+    total: number;
+    limit: number;
+    offset: number;
+    count: number;
+    events: HotEvent[];
+}
+interface Dropout {
+    best_rank: number | null;
+    best_score: number | null;
+    follower_count: number | null;
+    username: string;
+    nickname: string | null;
+    recruit_status: "available" | "contacted" | string;
+    check_age_minutes: number | null;
+    dropped_minutes_ago: number | null;
+}
+interface DropoutsResponse {
+    country: string;
+    division: string;
+    count: number;
+    dropouts: Dropout[];
+}
+interface ExportResponse {
+    country: string;
+    source: "league" | "gaming" | "daily";
+    count: number;
+    truncated: boolean;
+    rows: Record<string, unknown>[];
+}
+interface ResolvedCreator {
+    username: string;
+    nickname: string | null;
+    avatar: string | null;
+    verified: boolean;
+    follower_count: number | null;
+    live: boolean;
+}
+type ResolveResponse = {
+    found: true;
+    creator: ResolvedCreator;
+} | {
+    found: false;
+    username: string;
+};
+interface Gifter {
+    rank: number;
+    gifter_id: string;
+    username: string;
+    diamonds: number;
+    est_value_usd: number;
+    diamonds_7d: number | null;
+    creators_gifted: number | null;
+    gifts: number | null;
+    last_seen: string | null;
+}
+interface GiftersPage {
+    country: string;
+    sort: "lifetime" | "7d";
+    total_estimated: number | null;
+    limit: number;
+    offset: number;
+    count: number;
+    gifters: Gifter[];
+}
+interface GifterDetail {
+    gifter: {
+        gifter_id: string;
+        username: string;
+        country: string;
+        diamonds: number;
+        est_value_usd: number;
+        diamonds_7d: number | null;
+        diamonds_30d: number | null;
+        gifts: number | null;
+        creators_gifted: number | null;
+        first_seen: string | null;
+        last_seen: string | null;
+    };
+    creators: {
+        creator: string;
+        diamonds: number;
+        est_value_usd: number;
+        gifts: number | null;
+        last_gifted: string | null;
+    }[];
+}
 declare class RngrowError extends Error {
     /** Machine-readable error code, e.g. "country_not_in_plan" or "rate_limited". */
     readonly code: string;
@@ -169,6 +269,7 @@ declare class Rngrow {
     private readonly fetchImpl;
     constructor(apiKey: string, options?: RngrowOptions);
     private request;
+    private requestText;
     /** Key introspection: plan, countries, rate limits, usage today. */
     me(): Promise<Me>;
     readonly creators: {
@@ -187,6 +288,10 @@ declare class Rngrow {
         stats: (params: {
             country: string;
         }) => Promise<CreatorStats>;
+        /** Resolve a TikTok handle in real time: profile + LIVE-right-now status. */
+        resolve: (params: {
+            username: string;
+        }) => Promise<ResolveResponse>;
         /**
          * Iterate the whole pool with automatic cursor pagination.
          *
@@ -235,7 +340,52 @@ declare class Rngrow {
         hot: (params: {
             country: string;
         }) => Promise<HotCreators>;
+        /** Past HOT / diamond spike events, up to 30 days back. */
+        hotHistory: (params: {
+            country: string;
+            days?: number;
+            division?: string;
+            username?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<HotHistoryPage>;
+        /** Creators who fell off a division's board and are still recruitable. */
+        dropouts: (params: {
+            country: string;
+            division: string;
+        }) => Promise<DropoutsResponse>;
+        /** Bulk board export as JSON, up to 25,000 rows. */
+        export: (params: {
+            country: string;
+            source?: "league" | "gaming" | "daily";
+            divisions?: string[];
+            games?: string[];
+            availableOnly?: boolean;
+            maxScore?: number;
+        }) => Promise<ExportResponse>;
+        /** Bulk board export as a ready-to-save CSV string. */
+        exportCsv: (params: {
+            country: string;
+            source?: "league" | "gaming" | "daily";
+            divisions?: string[];
+            games?: string[];
+            availableOnly?: boolean;
+            maxScore?: number;
+        }) => Promise<string>;
+    };
+    readonly gifters: {
+        /** The country's top gift senders (whales), lifetime or rolling 7 days. */
+        list: (params: {
+            country: string;
+            sort?: "lifetime" | "7d";
+            limit?: number;
+            offset?: number;
+        }) => Promise<GiftersPage>;
+        /** One gifter's profile and exactly which creators they fund. */
+        detail: (params: {
+            gifterId: string;
+        }) => Promise<GifterDetail>;
     };
 }
 
-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 };
+export { type Creator, type CreatorStats, type CreatorsPage, type DailyBoard, type Dropout, type DropoutsResponse, type ExportResponse, type GamingBoard, type GamingGame, type Gifter, type GifterDetail, type GiftersPage, type HotCreator, type HotCreators, type HotEvent, type HotHistoryPage, type LeagueAvailableCreator, type LeagueAvailablePage, type LeagueBoard, type LeagueBoardRow, type LeagueCoverage, type LeagueDivision, type Me, type RankingRow, type ResolveResponse, type ResolvedCreator, Rngrow, RngrowError, type RngrowOptions, Rngrow as default };

package/dist/index.js

@@ -25,6 +25,8 @@ var Rngrow = class {
       }),
       /** Discovery volume for a country. */
       stats: (params) => this.request("/creators/stats", { country: params.country }),
+      /** Resolve a TikTok handle in real time: profile + LIVE-right-now status. */
+      resolve: (params) => this.request("/creators/resolve", { username: params.username }),
       /**
        * Iterate the whole pool with automatic cursor pagination.
        *
@@ -69,7 +71,36 @@ var Rngrow = class {
       /** 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)
+      hot: (params) => this.request("/leagues/hot", params),
+      /** Past HOT / diamond spike events, up to 30 days back. */
+      hotHistory: (params) => this.request("/leagues/hot/history", params),
+      /** Creators who fell off a division's board and are still recruitable. */
+      dropouts: (params) => this.request("/leagues/dropouts", params),
+      /** Bulk board export as JSON, up to 25,000 rows. */
+      export: (params) => this.request("/leagues/export", {
+        country: params.country,
+        source: params.source,
+        divisions: params.divisions?.join(","),
+        games: params.games?.join(","),
+        available_only: params.availableOnly === false ? "false" : void 0,
+        max_score: params.maxScore
+      }),
+      /** Bulk board export as a ready-to-save CSV string. */
+      exportCsv: (params) => this.requestText("/leagues/export", {
+        country: params.country,
+        source: params.source,
+        divisions: params.divisions?.join(","),
+        games: params.games?.join(","),
+        available_only: params.availableOnly === false ? "false" : void 0,
+        max_score: params.maxScore,
+        format: "csv"
+      })
+    };
+    this.gifters = {
+      /** The country's top gift senders (whales), lifetime or rolling 7 days. */
+      list: (params) => this.request("/gifters", params),
+      /** One gifter's profile and exactly which creators they fund. */
+      detail: (params) => this.request(`/gifters/${encodeURIComponent(params.gifterId)}`)
     };
     if (!apiKey || !apiKey.startsWith("rng_")) {
       throw new Error(
@@ -111,6 +142,28 @@ var Rngrow = class {
     }
     return body;
   }
+  async requestText(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 }
+    });
+    if (!res.ok) {
+      let code = "server_error";
+      let message = `Request failed with HTTP ${res.status}`;
+      try {
+        const body = await res.json();
+        if (body?.error?.code) code = body.error.code;
+        if (body?.error?.message) message = body.error.message;
+      } catch {
+      }
+      const retryHeader = res.headers.get("Retry-After");
+      throw new RngrowError(code, message, res.status, retryHeader ? Number(retryHeader) || void 0 : void 0);
+    }
+    return res.text();
+  }
   /** Key introspection: plan, countries, rate limits, usage today. */
   me() {
     return this.request("/me");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rngrow/sdk",
-  "version": "0.1.1",
+  "version": "0.2.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",