@toktikhq/sdk-js 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1754 @@
+/** Honest position of a response inside the product's published Coverage Set. */
+declare const COVERAGE_STATUSES: readonly ["observed", "partial", "not-covered", "not-offered", "stale"];
+type CoverageStatus = (typeof COVERAGE_STATUSES)[number];
+/** How current the persisted observation is; refreshes are always asynchronous. */
+declare const FRESHNESS_STATUSES: readonly ["near_realtime", "historical", "stale"];
+type FreshnessStatus = (typeof FRESHNESS_STATUSES)[number];
+interface Provenance {
+    /** RFC 3339 instant of the newest observation represented by this response. */
+    observedAt: string;
+    freshness: FreshnessStatus;
+    /** Collector or persisted dataset that produced the observation. */
+    source: string;
+    coverageStatus: CoverageStatus;
+    /** Version of the calculation or projection used to produce the data. */
+    methodologyVersion: string;
+}
+/** Every customer-facing data resource is wrapped so provenance cannot be omitted. */
+interface ProvenanceEnvelope<TData> {
+    data: TData;
+    provenance: Provenance;
+}
+
+interface LiveSessionGiftRollup {
+    giftId: string;
+    giftName: string | null;
+    giftType: number | null;
+    giftCount: number;
+    diamondTotal: number;
+    senderCount: number;
+}
+interface LiveSessionGifterRollup {
+    gifterUserId: string;
+    gifterUniqueId: string | null;
+    gifterNickname: string | null;
+    giftCount: number;
+    diamondTotal: number;
+}
+interface LiveSessionSummary {
+    id: string;
+    roomKey: string;
+    roomId: string;
+    creatorUniqueId: string | null;
+    /** Observed avatar for `creatorUniqueId`, joined best-effort from `creator_profiles` (null = never profiled). */
+    creatorAvatarUrl: string | null;
+    startedAt: string;
+    endedAt: string | null;
+    durationSeconds: number;
+    peakViewerCount: number;
+    eventCount: number;
+    chatCount: number;
+    giftCount: number;
+    totalGiftDiamonds: number;
+}
+interface LiveSessionRecord extends LiveSessionSummary {
+    giftRollups: LiveSessionGiftRollup[];
+    gifterRollups: LiveSessionGifterRollup[];
+}
+interface LiveCreatorPerformanceRecord {
+    sessionId: string;
+    sessionStartedAt: string;
+    creatorUniqueId: string;
+    roomKey: string;
+    durationSeconds: number;
+    peakViewerCount: number;
+    eventCount: number;
+    chatCount: number;
+    giftCount: number;
+    totalGiftDiamonds: number;
+    distinctGifterCount: number;
+}
+interface LiveSessionListResponse {
+    items: LiveSessionSummary[];
+    nextCursor: string | null;
+    /**
+     * P1.7 — the caller's plan-tier history read window in days (`null` = unlimited). Sessions that
+     * started before `now - historyWindowDays` are withheld; a higher tier reads further back.
+     */
+    historyWindowDays: number | null;
+    /** True when sessions older than the window exist and were withheld by it (not by paging). */
+    historyTruncated: boolean;
+}
+interface LiveCreatorPerformanceListResponse {
+    items: LiveCreatorPerformanceRecord[];
+    nextCursor: string | null;
+    /** P1.7 — plan-tier history read window in days (`null` = unlimited). See {@link LiveSessionListResponse}. */
+    historyWindowDays: number | null;
+    /** True when performance rows older than the window exist and were withheld by it. */
+    historyTruncated: boolean;
+}
+
+/** Rank movement of a creator versus the immediately-prior published period. */
+declare const RANKING_MOVEMENTS: readonly ["up", "down", "same", "new"];
+type RankingMovement = (typeof RANKING_MOVEMENTS)[number];
+interface RankingEntry {
+    rank: number;
+    creatorUid: string;
+    uniqueId: string | null;
+    nickname: string | null;
+    /**
+     * Creator avatar URL, extracted from the captured board row (no new TikTok call). `null` only when
+     * the board row carried none. Shown even on a `masked` row (owner decision 2026-08-01: the photo is
+     * public TikTok data; masking withholds the handle/name, not the avatar). `secUid` is never included
+     * in a ranking entry, masked or not.
+     */
+    avatarUrl: string | null;
+    /**
+     * Whether the creator is live *right now* in a room the platform is currently observing (joined
+     * from `room_catalog` runtime state — best-effort over the tracked set, never a new upstream call).
+     */
+    isLive: boolean;
+    /** The observed live room id when `isLive`, else `null`. */
+    roomId: string | null;
+    /** Board score (TikTok board points/diamonds). */
+    score: number;
+    leagueClass: string | null;
+    /**
+     * Where `leagueClass` came from. `"observed"` = the row's own board carries the class (a league
+     * board). `"last_phase"` = the class was carried over from the most recent league phase this
+     * creator was observed in, because the board being read (Daily, Popular LIVE, Gaming) does not
+     * carry one and TikTok publishes no league board between competition phases. `null` when
+     * `leagueClass` is null. A carried-over class is real observed data, never inferred — but it
+     * describes a past phase, so `leagueClassAsOf` dates it.
+     */
+    leagueClassSource: "observed" | "last_phase" | null;
+    /** When `leagueClassSource` is `"last_phase"`, when that class was observed; else `null`. */
+    leagueClassAsOf: string | null;
+    movement: RankingMovement;
+    /** Creator's rank in the prior published period, or null when new/unknown. */
+    previousRank: number | null;
+    /**
+     * R5.1 paywall — when `true`, `uniqueId`/`nickname` are masked (e.g. `•••••ry`); `rank`/`score`/
+     * `movement`/`isLive`/`avatarUrl` still show (teaser — avatar shown even when masked, owner decision
+     * 2026-08-01). Enforced at the API serializer by the viewer's plan tier, not just hidden in the UI.
+     * `unmaskTier` names the tier that unlocks the handle/name.
+     */
+    masked: boolean;
+    /**
+     * When `masked`, the plan tier that unlocks the real identity (for an Unlock CTA); else `null`.
+     * P1.10 — this is the unlock tier for the BOARD being read, not a constant: standard boards unlock
+     * at `pro`, league boards at `scale`, gaming boards at `agency` (`@v2/billing` `UNMASK_TIER_BY_BOARD`).
+     */
+    unmaskTier: string | null;
+}
+interface OfficialRankingBoard {
+    kind: "official";
+    /** TikTok board key (e.g. "daily", "hourly", "popular_live", "gaming_daily", "shopping_daily", "shopping_weekly"). */
+    board: string;
+    /** Region = ISO country code the board was captured for. */
+    region: string;
+    /** Board period key from the captured snapshot (empty when gated/absent). */
+    periodKey: string;
+    /**
+     * ISO instant at which the board's CURRENT period next rolls — what the UI counts down to
+     * ("Next update in …"). For boards whose `periodKey` is an `ends-at:<ISO>` (hourly/daily/gaming/
+     * popular/shopping) this is that same instant. For the league boards, whose `periodKey` is a 2-hour
+     * sampling bucket (an intra-phase observation, not a period with a reset), it is the board's own
+     * `next_period_time_stamp` captured in the snapshot evidence — so a league board can show an honest
+     * countdown too. `null` when no reset instant is known (a gated board, or a `previous-of:` / bare
+     * legacy key that states none). A past instant means the period is rolling; the client renders that
+     * as "updating" rather than a negative remainder. Optional so an older client/fixture that omits
+     * it stays valid; the live API always sets it (to an instant or `null`).
+     */
+    resetAt?: string | null;
+    /**
+     * Whether THIS board is inside the Coverage Set — i.e. its own latest snapshot is `complete`.
+     * When false the board is **gated**: `entries` is empty and `coverageStatus` explains whether
+     * collection is incomplete (`not-covered`) or TikTok does not publish it here (`not-offered`).
+     * The gating unit is the board, not
+     * the region: a region's other boards (including league classes the product never publishes,
+     * which TikTok withdraws entirely between competition phases) no longer withhold a board that
+     * is itself complete and fresh.
+     */
+    publishable: boolean;
+    /** Coverage of the board's region — reported as context, not the gate. */
+    coverage: RankingCoverage;
+    /**
+     * Present only on a per-game gaming board (`board = "gaming_game"`, R6.4): which game this board
+     * is, so the client need not echo its own request. `gameKey` is TikTok's stable game identity
+     * (e.g. `topic_game_roblox`); `gameTitle` is the display name at capture time (may be null before
+     * any snapshot). Absent on every non-game board.
+     */
+    game?: {
+        gameKey: string;
+        gameTitle: string | null;
+    };
+    entries: RankingEntry[];
+}
+interface RankingCoverage {
+    /** Complete boards observed for the region. */
+    completeBoards: number;
+    /** Boards expected for full coverage (22 per ADR-006). */
+    expectedBoards: number;
+    /** completeBoards / expectedBoards, clamped to [0,1]. */
+    ratio: number;
+    /** Publish threshold this board was gated against, in [0,1]. */
+    threshold: number;
+}
+/**
+ * One retained period of an Official board, as captured (R5.5).
+ *
+ * A period is served as it was observed: there is no live-join (a past board's `isLive` is always
+ * `false` and its `roomId` `null` — today's rooms say nothing about a board captured weeks ago) and
+ * no movement, which is a property of the *current* board versus the one before it, not of a period
+ * sitting in history. The only added field is `leagueClass`, carried over from the creator's last
+ * observed league phase and marked `last_phase` with `leagueClassAsOf` — the boards customers read
+ * publish no class at all, so without it the `leagueTier` filter would match nothing.
+ *
+ * Periods that were only partially captured, or that TikTok did not publish at all, are returned
+ * WITH their own `coverageStatus` rather than hidden: a gap in the record is part of the record.
+ */
+interface RankingHistoryPeriod {
+    /** Board period key from the captured snapshot (e.g. `ends-at:2026-07-29T17:00:00.000Z`). */
+    periodKey: string;
+    /** When this period's board was captured (ISO 8601). */
+    observedAt: string;
+    /** This period's own coverage: `observed` when completely captured, else `partial`. */
+    coverageStatus: CoverageStatus;
+    /** Whether this period was completely captured (an incomplete period is shown, not published). */
+    publishable: boolean;
+    entries: RankingEntry[];
+}
+/**
+ * Retained Official-ranking history for the AUTHENTICATED lane (R5.5).
+ *
+ * The public showroom has its own history feed, but it applies the public teaser rule
+ * (`masked = isLive || rank > openTopN`) — which withholds exactly the rows a paying customer
+ * bought. This response applies the same plan-tier masking as `/v1/rankings/official`, so `/v1`
+ * never returns less identity than the public projection (ADR-014).
+ */
+interface RankingHistoryResponse {
+    /** TikTok board key the history was read for. */
+    board: string;
+    /** Region = ISO country code. */
+    region: string;
+    /** Retained periods, newest first. */
+    periods: RankingHistoryPeriod[];
+    /** Opaque cursor for the next (older) page, or `null` when the last page was returned. */
+    nextCursor: string | null;
+    /** Whether more retained periods may exist beyond the oldest one returned. */
+    hasMore: boolean;
+    /**
+     * P1.7 — the caller's plan-tier history read window in days (`null` = unlimited). The response is
+     * capped to periods within it; a higher tier reads further back into the same retained data.
+     */
+    historyWindowDays: number | null;
+    /**
+     * True when older retained periods exist beyond `historyWindowDays` and were withheld by the
+     * window (not by paging). Lets the UI say "N more at a higher tier" instead of a silent cut that
+     * reads as "we have no more data".
+     */
+    historyTruncated: boolean;
+}
+interface OfficialRankingResponse {
+    board: OfficialRankingBoard;
+}
+/**
+ * LT1.3 — region "movers": the creators whose rank changed most between a board's current and
+ * previous published period, split into gainers (moved up) and losers (moved down). Derived from the
+ * same official board read (`movement`/`previousRank` already carried per entry), so identity is
+ * masked by the viewer's plan tier exactly as `OfficialRankingResponse` — never an unmask backdoor.
+ */
+interface RankMoversBoard {
+    board: string;
+    region: string;
+    periodKey: string;
+    /** Gainers, biggest rank gain first (rank number fell the most). Empty on a gated/unpublished board. */
+    gainers: RankingEntry[];
+    /** Losers, biggest rank drop first (rank number rose the most). */
+    losers: RankingEntry[];
+}
+interface RankMoversResponse {
+    board: RankMoversBoard;
+}
+/**
+ * One region a customer can actually read a rank board for (R5.7).
+ *
+ * `region` is the **bucket key** every other rankings route accepts — `US+`, `MENA`, `LATAM`, … —
+ * not an ISO country code. TikTok's boards are keyed by bucket, and a bucket can span several
+ * countries (`ES+` contains Mexico; `UK+` is anglophone-Africa-heavy). Asking for `US`, `GB` or
+ * `DE` matches no board at all, which is exactly the bug this list exists to close: a UI that
+ * invents ISO codes shows a dozen regions that can only ever come back coverage-gated.
+ */
+interface RankingRegion {
+    /** Bucket key, verbatim — pass this to `board`/`history` reads. Never normalised. */
+    region: string;
+    /**
+     * Human label. A multi-country bucket says so (`"UK+ · United Kingdom & anglophone Africa"`)
+     * rather than flying one country's flag over several. An unrecognised bucket labels itself.
+     */
+    label: string;
+    /** This region's coverage, on the same terms `/v1/rankings/official` reports it. */
+    coverage: RankingCoverage;
+    /**
+     * Board keys TikTok currently offers in this region and that we have captured at least once,
+     * sorted. A listed board can still be gated while its latest capture is incomplete.
+     */
+    boards: string[];
+    /**
+     * Board keys proven absent from TikTok's product in this region, sorted — the set a client may
+     * present as unavailable.
+     *
+     * Deliberately its own field rather than "whatever is missing from `boards`". Absence from
+     * `boards` means only "no capture yet", which is also true of a board we have simply never
+     * reached; a client that read absence as proof of upstream absence would tell a customer "TikTok
+     * does not publish this board here" on the strength of our own gap — the exact false reason R5.6
+     * exists to remove — and, by disabling the control, leave no way to reach the honest
+     * `not-covered` answer.
+     */
+    notOfferedBoards: string[];
+}
+/**
+ * The regions a customer can read, built from what has actually been captured (R5.7).
+ *
+ * Deliberately NOT the configured allowlist: a region we intend to crawl but have never captured
+ * would be an invitation to an empty board. Empty is a valid answer — an empty array, not an error.
+ */
+interface RankingRegionsResponse {
+    regions: RankingRegion[];
+}
+/**
+ * One per-game gaming board a region offers (R6.4) — the source the games selector reads so the UI
+ * never hardcodes a game list (same principle as `RankingRegionsResponse`).
+ */
+interface GamingGame {
+    /** TikTok's stable game identity — pass this verbatim as the `game` param on a `gaming_game` read. */
+    gameKey: string;
+    /** Display name from the latest capture (session-locale default pattern); null before any snapshot. */
+    gameTitle: string | null;
+    /**
+     * `offered` = advertised by TikTok's game switcher (or captured at least once); `not_offered` =
+     * proven pulled. A client presents `not_offered` games as unavailable rather than hiding them.
+     */
+    status: "offered" | "not_offered";
+    /** ISO instant this game's board next resets (from the latest snapshot's `ends-at:` period); null if unknown. */
+    resetAt: string | null;
+}
+/**
+ * The per-game gaming boards a region offers, built from captured snapshots + availability (R6.4).
+ * Empty array = the region runs the aggregate gaming board but TikTok has enabled no per-game tabs
+ * there — a valid answer, not an error, and the UI shows no game selector.
+ */
+interface GamingGamesResponse {
+    region: string;
+    games: GamingGame[];
+}
+
+/**
+ * The discrete observation window every gifter read is scoped to. There is no "all-time" option: the
+ * store is presence-based and coverage-biased, so an unbounded total would read as a lifetime figure
+ * it is not. The window is echoed on every response so a number is never shown unlabelled.
+ */
+declare const GIFTER_WINDOWS: readonly ["24h", "7d", "30d"];
+type GifterWindow = (typeof GIFTER_WINDOWS)[number];
+/**
+ * Stable public identity of a gifter. `gifterKey` is what every other endpoint takes:
+ * the TikTok `sec_uid` when the upstream event carried one, else a `uid:<userId>`
+ * fallback. `identity` says which, so a caller never mistakes a fallback for a sec_uid.
+ */
+declare const GIFTER_IDENTITY_KINDS: readonly ["sec_uid", "user_id_fallback"];
+type GifterIdentityKind = (typeof GIFTER_IDENTITY_KINDS)[number];
+/**
+ * LT3.1 — a gifter archetype, derived (first-match) from the OBSERVED figures below. Like every gifter
+ * number it is a proxy over the rooms we watched, never a claim about the gifter's true TikTok-wide
+ * behaviour (LT3.2 "true LTV" is a separate, gated question). Rules, in precedence order:
+ *  - `whale`    — high absolute observed diamonds (`observedDiamonds >= WHALE_DIAMONDS`).
+ *  - `one_time` — seen giving in a single session (`sessionCount <= 1`).
+ *  - `rising`   — recently arrived (`firstSeenAt` within `RISING_TENURE_DAYS`) and already multi-session.
+ *  - `dormant`  — established but gone quiet (`now - lastSeenAt > DORMANT_DAYS`).
+ *  - `regular`  — the rest: sustained, active, sub-whale.
+ */
+declare const GIFTER_SEGMENTS: readonly ["whale", "one_time", "rising", "dormant", "regular"];
+type GifterSegment = (typeof GIFTER_SEGMENTS)[number];
+interface GifterSummary {
+    gifterKey: string;
+    identity: GifterIdentityKind;
+    secUid: string | null;
+    uniqueId: string | null;
+    nickname: string | null;
+    /**
+     * PD4 (#4) — resolved gifter avatar, best-effort via the signed profile endpoint and cached
+     * (`gifter_avatars`), bounded to the gifters on the page. Null when the gifter is anonymous (no
+     * resolvable id), the resolve failed, or the resolver is disabled — the surface then falls back to
+     * a gradient. Never an invented image.
+     */
+    avatarUrl: string | null;
+    /** Diamonds observed from this gifter in the requested window (union-max per session, summed). */
+    observedDiamonds: number;
+    /**
+     * PD5 (#10) — `observedDiamonds` estimated in USD at the configured `DIAMOND_USD_RATE` (creator-
+     * received value). An "est." over an observed, windowed figure — never a settled payout. Null when
+     * the amount is not estimable.
+     */
+    estimatedValueUsd: number | null;
+    /** Distinct rooms/sessions this gifter was observed giving in, in the window. */
+    sessionCount: number;
+    /** Distinct creators this gifter was observed funding in the window. */
+    creatorCount: number;
+    /** R6 — the ranked board's ISO country this gifter was observed in (the whale board's Region
+     * column). MAX across their observations, so a whale seen in several regions gets one label. Null
+     * until region coverage (0065) reaches them. */
+    region: string | null;
+    /** R6 — distinct regions observed (0066): 0 none, 1 single (`region` names it), >1 multi-region
+     * (the board shows "Multi (n)" rather than one arbitrary country). */
+    regionCount: number;
+    /** LT3.1 — the gifter's archetype, derived from the observed figures (see {@link GifterSegment}). */
+    segment: GifterSegment;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    /**
+     * P-gifter-mask — identity paywall, mirroring the rankings board rule (`rankUnmaskPolicy`, `standard`
+     * board: unmask at Pro, teaser top 10). When `true`, `nickname`/`uniqueId`/`secUid`/`gifterKey` are
+     * withheld (`nickname`/`uniqueId` → `•••••XX`, `secUid` → `null`, `gifterKey` → a non-resolvable
+     * masked token); `avatarUrl`/`observedDiamonds`/`segment`/counts still show (owner decision: the
+     * avatar shows even on a masked row, exactly like a rankings entry). The top-N teaser rows are `false`.
+     */
+    masked: boolean;
+    /** When `masked`, the plan tier that unlocks the real identity (for an Unlock CTA); else `null`. */
+    unmaskTier: string | null;
+}
+/** One creator a gifter funds, with what they were observed giving to that creator in the window. */
+interface FundedCreator {
+    creatorUniqueId: string;
+    /** Observed display name, joined best-effort from `creator_profiles` (null = never profiled). */
+    creatorDisplayName: string | null;
+    /** Observed avatar for `creatorUniqueId`, joined best-effort from `creator_profiles` (null = never profiled). */
+    creatorAvatarUrl: string | null;
+    observedDiamonds: number;
+    /** PD5 (#10) — `observedDiamonds` as an "est." USD value at `DIAMOND_USD_RATE`. Null when not estimable. */
+    estimatedValueUsd: number | null;
+    sessionCount: number;
+    firstSeenAt: string;
+    lastSeenAt: string;
+}
+/** One gifter funding a creator, with what they were observed giving to that creator in the window. */
+interface CreatorGifter {
+    gifterKey: string;
+    identity: GifterIdentityKind;
+    secUid: string | null;
+    uniqueId: string | null;
+    nickname: string | null;
+    /** PD4 (#4) — resolved gifter avatar (see {@link GifterSummary.avatarUrl}); null → gradient fallback. */
+    avatarUrl: string | null;
+    observedDiamonds: number;
+    /** PD5 (#10) — `observedDiamonds` as an "est." USD value at `DIAMOND_USD_RATE`. Null when not estimable. */
+    estimatedValueUsd: number | null;
+    sessionCount: number;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    /** P-gifter-mask — identity paywall, same rule as {@link GifterSummary.masked} (top-N teaser per
+     * creator unmasked, the rest withheld below the unlock tier). */
+    masked: boolean;
+    /** When `masked`, the plan tier that unlocks the real identity (for an Unlock CTA); else `null`. */
+    unmaskTier: string | null;
+}
+interface GifterListResponse {
+    gifters: GifterSummary[];
+    /** Echo of the applied window + creator filter, so a cached page is self-describing. */
+    filter: {
+        window: GifterWindow;
+        creatorUniqueId: string | null;
+    };
+}
+interface GifterProfileResponse {
+    gifter: GifterSummary;
+    fundedCreators: FundedCreator[];
+    /** The window the profile's figures are scoped to. */
+    filter: {
+        window: GifterWindow;
+    };
+}
+/** Aggregate over ALL of a creator's observed gifters in the window (not just the returned page) —
+ * the "total" strip on the Whale intel modal. */
+interface CreatorGifterTotals {
+    observedDiamonds: number;
+    gifterCount: number;
+    /** `observedDiamonds` × `DIAMOND_USD_RATE`; null when not estimable. */
+    estimatedValueUsd: number | null;
+}
+interface CreatorGiftersResponse {
+    creatorUniqueId: string;
+    gifters: CreatorGifter[];
+    totals: CreatorGifterTotals;
+    filter: {
+        window: GifterWindow;
+    };
+}
+
+/** One retained observation of a creator's metrics over time. */
+interface CreatorProfileHistoryPoint {
+    /** RFC 3339 capture instant. */
+    capturedAt: string;
+    followerCount: number | null;
+    followingCount: number | null;
+    awemeCount: number | null;
+    totalFavorited: number | null;
+    favoritingCount: number | null;
+    region: string | null;
+    displayName: string | null;
+    verified: boolean | null;
+}
+interface CreatorProfileData {
+    /** Stable numeric TikTok user id. */
+    tiktokUserId: string;
+    /** Current handle (may be recycled across accounts over time). */
+    uniqueId: string;
+    secUid: string | null;
+    displayName: string | null;
+    region: string | null;
+    language: string | null;
+    signature: string | null;
+    avatarUrl: string | null;
+    followerCount: number | null;
+    followingCount: number | null;
+    awemeCount: number | null;
+    totalFavorited: number | null;
+    favoritingCount: number | null;
+    verified: boolean | null;
+    customVerify: string | null;
+    enterpriseVerifyReason: string | null;
+    instagramId: string | null;
+    youtubeChannelId: string | null;
+    twitterId: string | null;
+    /** RFC 3339 first observation / newest refresh instants. */
+    firstSeenAt: string;
+    lastRefreshedAt: string;
+    /** Newest-first metric history (bounded). */
+    history: CreatorProfileHistoryPoint[];
+}
+type CreatorProfileResponse = ProvenanceEnvelope<{
+    creator: CreatorProfileData;
+}>;
+/** A lightweight creator row for the search/discovery grid (no history). */
+interface CreatorSearchResult {
+    tiktokUserId: string;
+    uniqueId: string;
+    displayName: string | null;
+    region: string | null;
+    avatarUrl: string | null;
+    followerCount: number | null;
+    verified: boolean | null;
+    /** LT2.1 — whether this creator is live right now in a room the platform is observing. */
+    isLive: boolean;
+    /**
+     * LT2.1 recruiting-finder paywall — `true` when the caller's plan tier hides this creator's
+     * identity (`uniqueId`/`displayName` are `•••••…`); `region`/`followerCount`/`isLive`/`avatarUrl`
+     * still show. Only the filter-driven finder masks (a `q` handle-search never does — you already
+     * know who you searched for). `unmaskTier` names the tier that reveals the identity.
+     */
+    masked: boolean;
+    /** When `masked`, the plan tier that unlocks the real identity (for an Unlock CTA); else `null`. */
+    unmaskTier: string | null;
+}
+/** Search/browse over the already-observed creator set (never a live TikTok search). An empty
+ * query browses the most-followed observed creators. `nextCursor` pages the recruiting finder
+ * (region/minFollowers/liveNow/sort filters); `null` on the last page (and on a plain `q` search). */
+type CreatorSearchResponse = ProvenanceEnvelope<{
+    query: string;
+    results: CreatorSearchResult[];
+    nextCursor: string | null;
+}>;
+interface CreatorProfileChange {
+    /** Tracked field name, e.g. `uniqueId`, `displayName`, `avatarUrl`. */
+    field: string;
+    oldValue: string | null;
+    newValue: string | null;
+    /** RFC 3339 instant the change was first observed (not when it happened on TikTok). */
+    observedAt: string;
+    /** Collector that observed it, e.g. `profile-resolve`. */
+    source: string;
+}
+interface CreatorChangesData {
+    tiktokUserId: string;
+    uniqueId: string;
+    /** Newest-first. Empty when nothing has changed since we started observing. */
+    changes: CreatorProfileChange[];
+}
+type CreatorChangesResponse = ProvenanceEnvelope<CreatorChangesData>;
+type FollowListDirection = "following" | "follower";
+/** One account in a follow list, with the profile fields TikTok embeds on every entry. */
+interface FollowListEntry {
+    tiktokUserId: string;
+    uniqueId: string;
+    secUid: string | null;
+    displayName: string | null;
+    avatarUrl: string | null;
+    region: string | null;
+    signature: string | null;
+    followerCount: number | null;
+    followingCount: number | null;
+    awemeCount: number | null;
+    verified: boolean | null;
+    /** RFC 3339 instants for the edge itself, not the account. */
+    firstSeenAt: string;
+    lastRefreshedAt: string;
+}
+interface FollowListData {
+    /** The account whose list this is. */
+    tiktokUserId: string;
+    uniqueId: string;
+    direction: FollowListDirection;
+    entries: FollowListEntry[];
+    /** Opaque; pass back as `?cursor=`. `null` when there is nothing further to serve. */
+    nextCursor: string | null;
+    hasMore: boolean;
+    /** TikTok's own follower/following count — for `follower` this dwarfs `storedCount` by design. */
+    totalReported: number | null;
+    /** How many entries we actually hold for this list. */
+    storedCount: number;
+    /** True when TikTok reports the account hides this list; nothing can be collected. */
+    isPrivate: boolean;
+}
+type FollowListResponse = ProvenanceEnvelope<FollowListData>;
+
+interface CreatorAnalysisSubject {
+    tiktokUserId: string;
+    uniqueId: string;
+    displayName: string | null;
+    /** Observed avatar from `creator_profiles` — the same photo the profile surface shows. */
+    avatarUrl: string | null;
+    region: string | null;
+    verified: boolean | null;
+    followerCount: number | null;
+    followingCount: number | null;
+    /** Videos TikTok says the account has, which is normally far more than we analysed. */
+    awemeCount: number | null;
+    totalFavorited: number | null;
+    firstSeenAt: string;
+    lastRefreshedAt: string;
+}
+/** What the report was actually computed over. */
+interface CreatorAnalysisSample {
+    videosAnalyzed: number;
+    /** RFC 3339 create-time of the oldest / newest analysed video (`null` if none carried one). */
+    oldestVideoAt: string | null;
+    newestVideoAt: string | null;
+    /** Days between oldest and newest analysed video. `null` with fewer than two dated videos. */
+    spanDays: number | null;
+    /** `videosAnalyzed / awemeCount`, 0..1 — how much of the account this report saw. */
+    shareOfCatalog: number | null;
+}
+/**
+ * Engagement over the sample. Rates are **sums over sums** (total likes ÷ total plays), not the
+ * mean of per-video rates: one viral video should move the number in proportion to its size, and
+ * averaging ratios lets a 200-view video weigh as much as a 20M-view one.
+ */
+interface CreatorAnalysisEngagement {
+    totalPlays: number;
+    totalLikes: number;
+    totalComments: number;
+    totalShares: number;
+    avgPlays: number;
+    medianPlays: number;
+    avgLikes: number;
+    avgComments: number;
+    avgShares: number;
+    /** (likes + comments + shares) ÷ plays. `null` when no analysed video carries a play count. */
+    engagementRate: number | null;
+    likeRate: number | null;
+    commentRate: number | null;
+    shareRate: number | null;
+    /** avgPlays ÷ followers — reach per follower, `null` without a follower count. */
+    viewsPerFollower: number | null;
+}
+/** Posting rhythm over the sample window. */
+interface CreatorAnalysisCadence {
+    postsPerWeek: number | null;
+    avgDaysBetweenPosts: number | null;
+    longestGapDays: number | null;
+    /** 0 = Sunday … 6 = Saturday (UTC), by post count. `null` when nothing is dated. */
+    busiestWeekday: number | null;
+    /** Post counts per weekday, index 0 = Sunday (UTC). */
+    postsByWeekday: number[];
+}
+interface CreatorAnalysisVideo {
+    videoId: string;
+    description: string | null;
+    createTime: string | null;
+    playCount: number | null;
+    diggCount: number | null;
+    commentCount: number | null;
+    shareCount: number | null;
+    /** This video's own (likes + comments + shares) ÷ plays. */
+    engagementRate: number | null;
+}
+/** Comment-side signal, present only for videos whose comments were collected (R4.3). */
+interface CreatorAnalysisAudience {
+    commentsAnalyzed: number;
+    videosWithComments: number;
+    distinctCommenters: number;
+    avgLikesPerComment: number | null;
+    /** Commenters seen most often across the analysed comments, most-frequent first. */
+    topCommenters: {
+        uniqueId: string | null;
+        nickname: string | null;
+        avatarUrl: string | null;
+        comments: number;
+        likes: number;
+    }[];
+    /** Language mix of the analysed comments as a share of the total, most-common first. */
+    languages: {
+        language: string;
+        share: number;
+    }[];
+}
+/** Follower movement across retained profile snapshots. */
+interface CreatorAnalysisGrowth {
+    fromObservedAt: string;
+    toObservedAt: string;
+    days: number;
+    startFollowers: number;
+    endFollowers: number;
+    followerDelta: number;
+    /** Fractional change (0.042 = +4.2%). `null` when the first observation had no followers. */
+    followerDeltaRate: number | null;
+}
+/** A machine-readable caveat. The UI shows `message`; automation can branch on `code`. */
+interface CreatorAnalysisLimit {
+    code: "thin-video-sample" | "no-videos" | "no-play-counts" | "undated-videos" | "single-observation" | "no-comments";
+    message: string;
+}
+interface CreatorAnalysisData {
+    creator: CreatorAnalysisSubject;
+    sample: CreatorAnalysisSample;
+    /** `null` when we hold no videos for the creator — the report then covers profile counts only. */
+    engagement: CreatorAnalysisEngagement | null;
+    cadence: CreatorAnalysisCadence | null;
+    topByPlays: CreatorAnalysisVideo[];
+    topByEngagement: CreatorAnalysisVideo[];
+    /** `null` until R4.3 has collected comments for at least one of the analysed videos. */
+    audience: CreatorAnalysisAudience | null;
+    /** `null` until the creator has been observed at least twice. */
+    growth: CreatorAnalysisGrowth | null;
+    limits: CreatorAnalysisLimit[];
+}
+type CreatorAnalysisResponse = ProvenanceEnvelope<CreatorAnalysisData>;
+
+/** One retained observation of a video's metrics over time. */
+interface VideoMetricHistoryPoint {
+    capturedAt: string;
+    playCount: number | null;
+    diggCount: number | null;
+    commentCount: number | null;
+    shareCount: number | null;
+    collectCount: number | null;
+}
+interface VideoData {
+    videoId: string;
+    tiktokUserId: string;
+    uniqueId: string;
+    description: string | null;
+    createTime: string | null;
+    coverUrl: string | null;
+    durationSeconds: number | null;
+    playCount: number | null;
+    diggCount: number | null;
+    commentCount: number | null;
+    shareCount: number | null;
+    collectCount: number | null;
+    firstSeenAt: string;
+    lastRefreshedAt: string;
+}
+/** A single video with its metric history. */
+interface VideoWithHistory extends VideoData {
+    history: VideoMetricHistoryPoint[];
+}
+type CreatorVideosResponse = ProvenanceEnvelope<{
+    uniqueId: string;
+    tiktokUserId: string;
+    videos: VideoData[];
+}>;
+type VideoDetailResponse = ProvenanceEnvelope<{
+    video: VideoWithHistory;
+}>;
+/**
+ * D6.1 — one entry in a creator's active story tray. Ephemeral content fetched fresh through the
+ * signed mobile path (never stored), so a response is always the tray as it was at `observedAt`.
+ * Mirrors `PublicCreatorStory` in `@v2/tiktok-runtime` (kept here so `@v2/contracts` stays a leaf).
+ */
+interface StoryData {
+    /** Stable story/aweme id (string — exceeds 2^53, never JSON-parsed as a number). */
+    itemId: string;
+    kind: "photo" | "video";
+    /** Browser-renderable still: the photo, or the video cover. */
+    imageUrl: string | null;
+    /** Playable video address for a video story; `null` for a photo story. */
+    videoUrl: string | null;
+    createdAt: string | null;
+    expiresAt: string | null;
+    viewed: boolean;
+    isSubscriberOnly: boolean;
+}
+type CreatorStoriesResponse = ProvenanceEnvelope<{
+    uniqueId: string;
+    stories: StoryData[];
+}>;
+/**
+ * One public comment on a video (R4.3). Collected anonymously from TikTok's web comment endpoint
+ * and served in the order TikTok ranks them (its own relevance model, not chronological).
+ */
+interface VideoCommentData {
+    commentId: string;
+    videoId: string;
+    /** `null` for a top-level comment; the comment this one answers otherwise. */
+    parentCommentId: string | null;
+    authorUserId: string | null;
+    authorSecUid: string | null;
+    authorUniqueId: string | null;
+    authorNickname: string | null;
+    authorAvatarUrl: string | null;
+    text: string;
+    likeCount: number | null;
+    /** Replies under this comment upstream — fetch them with `?parentCommentId=<commentId>`. */
+    replyCount: number | null;
+    /** When the comment was posted; `null` when TikTok omits it. */
+    commentedAt: string | null;
+    language: string | null;
+    pinnedByAuthor: boolean;
+    likedByAuthor: boolean;
+    firstSeenAt: string;
+    lastRefreshedAt: string;
+}
+/**
+ * A page of comments. `nextCursor` is opaque — pass it back verbatim as `?cursor=`; `null` means
+ * there is nothing more to serve. `totalReported` is TikTok's own count for the thread, which is
+ * normally far larger than what we hold (the collector pages a bounded depth per request).
+ */
+type VideoCommentsResponse = ProvenanceEnvelope<{
+    videoId: string;
+    parentCommentId: string | null;
+    comments: VideoCommentData[];
+    nextCursor: string | null;
+    hasMore: boolean;
+    totalReported: number | null;
+    storedCount: number;
+}>;
+
+type TrendType = "hashtag" | "sound";
+interface TrendData {
+    trendType: TrendType;
+    trendId: string;
+    region: string;
+    title: string | null;
+    rank: number | null;
+    videoCount: number | null;
+    viewCount: number | null;
+    firstSeenAt: string;
+    lastRefreshedAt: string;
+}
+type TrendsResponse = ProvenanceEnvelope<{
+    region: string;
+    trends: TrendData[];
+}>;
+
+type RealtimeSubscriptionStatus = "queued" | "active" | "unavailable" | "offline" | "unsubscribed";
+interface RealtimeStatusFrame {
+    type: "status";
+    creatorId: string;
+    status: RealtimeSubscriptionStatus;
+    roomId?: string;
+    reason?: string;
+    requestId?: string;
+}
+/**
+ * Public realtime event frame. The event names deliberately match the event set stream-worker
+ * actually publishes; synthetic names are not advertised ahead of an upstream implementation.
+ */
+interface RealtimeEventFrame<T extends LiveEventType = LiveEventType> {
+    type: "event";
+    event: T;
+    eventId: string;
+    creatorId: string;
+    roomId: string;
+    sequence: number;
+    roomState: Extract<RoomRuntimeState, "active" | "ended" | "degraded">;
+    data: LiveEventPayloadByType[T];
+    provenance: Provenance;
+}
+interface RealtimeErrorFrame {
+    type: "error";
+    code: "invalid_message" | "invalid_creator" | "subscription_failed";
+    message: string;
+    requestId?: string;
+    retryable: boolean;
+}
+
+type ExportDataset = "live_sessions" | "rankings" | "gifters" | "creator_roster";
+/**
+ * The file formats the export writer can actually produce — the single runtime source of truth for
+ * "does the system support this format at all". `SUPPORTED_FORMATS` in the exports service derives
+ * from this list, and the pricing-page anti-drift test (P1.9 §3) asserts every `<format> export`
+ * line the pricing page advertises is a member of this set, so the shop window can never promise a
+ * format the code cannot emit. Tier *entitlement* (which formats YOUR plan may use) is a separate
+ * axis, enforced from `TIER_FEATURES.exportFormats` in `@v2/billing`.
+ */
+declare const EXPORT_FORMATS: readonly ["csv", "xlsx"];
+type ExportFormat = (typeof EXPORT_FORMATS)[number];
+type ExportJobStatus = "pending" | "ready" | "failed";
+interface ExportJob {
+    id: string;
+    dataset: ExportDataset;
+    format: ExportFormat;
+    status: ExportJobStatus;
+    rowCount: number;
+    filename: string;
+    /** Relative download path, present once the job is `ready`. */
+    downloadUrl: string | null;
+    error: string | null;
+    createdAt: string;
+    completedAt: string | null;
+}
+interface ExportJobListResponse {
+    items: ExportJob[];
+}
+
+/** Capability modules a workspace can be entitled to; sold separately or bundled (P1.1). */
+type EntitlementModule = "live" | "lookup";
+/** Commercial tier a workspace's plan normalises to. `agency` is the top published tier (P1.3). */
+type EntitlementTier = "free" | "starter" | "pro" | "scale" | "agency" | "enterprise";
+interface EntitlementLimits {
+    /** Max API-key requests per `rateWindowMs` (per key), matching the enforced sliding window. */
+    requestsPerWindow: number;
+    rateWindowMs: number;
+    /**
+     * P1.4 B4 — the same per-second ceiling the pricing page publishes, expressed per second regardless
+     * of how `rateWindowMs` is configured, so a client can size its own concurrency without inferring it
+     * from the window. `requestsPerMinute` is exactly this × 60.
+     */
+    apiRequestsPerSecond: number;
+    /** The enforced rolling per-UTC-day request quota. 0 = unlimited. Exceeding it returns 429. */
+    requestsPerDay: number;
+    /** Active API keys this workspace may hold; `POST /v1/api-keys` rejects beyond it. 0 = unlimited. */
+    maxApiKeys: number;
+    /** Realtime WS API: max concurrent subscribed rooms (demand-controller admission, D2.4). */
+    wsConcurrencyCap: number;
+    /** Realtime WS API: monthly room-minute ceiling. */
+    maxRoomMinutesPerMonth: number;
+    /**
+     * P1.7 — how far back (days from now) this workspace may READ its own history on the rankings /
+     * live-session / export routes. `null` = unlimited (the full retained record). This is a read
+     * window, not retention: raising the tier instantly widens it, it never deletes data.
+     */
+    historyWindowDays: number | null;
+    /**
+     * P1.8 — max active seats (members + pending invites) this workspace's plan allows. `0` = unlimited.
+     * `POST /v1/workspace/members/invite` rejects `409 seat_limit_reached` beyond it.
+     */
+    maxSeats: number;
+    /**
+     * P1.8 — seats in use right now (active members + pending invites), so the UI can show "N/M seats"
+     * and warn when a downgrade left the workspace over its cap, without recomputing it client-side.
+     */
+    seatsUsed: number;
+    /**
+     * P1.9 — the export file formats this workspace's plan is entitled to (`csv` / `xlsx`). `[]` = no
+     * export at all (Free). `POST /v1/exports` refuses `403 export_format_not_entitled` for a valid
+     * format not in this list, so the UI can render only the formats the plan can actually run.
+     */
+    exportFormats: ExportFormat[];
+}
+interface EntitlementCredits {
+    /** Billing period this balance covers, `YYYY-MM-01`. */
+    period: string;
+    monthlyAllotment: number;
+    hardCap: number;
+    spent: number;
+    remaining: number;
+}
+interface Entitlement {
+    workspaceId: string;
+    /** Raw `plans.code` currently assigned, or null when the workspace has no assignment. */
+    planCode: string | null;
+    tier: EntitlementTier;
+    /** Modules the workspace BOUGHT (or the bundle) — used at its own tier. */
+    modules: EntitlementModule[];
+    /**
+     * Modules the workspace did not buy but may use at FREE-tier terms (`FREE_FALLBACK_MODULES` in
+     * `@v2/billing` — today Lookup for a Live-only buyer; never Live). Empty for a bundle. A surface whose
+     * module is here is reachable (free caps/history), not locked behind the Plans upsell.
+     */
+    freeFallbackModules: EntitlementModule[];
+    /** Limits of the PURCHASED tier. Requests on a `freeFallbackModules` module run under `TIER_CAPS.free`
+     *  (their own throttle bucket), not these. */
+    limits: EntitlementLimits;
+    credits: EntitlementCredits;
+}
+/** `GET /v1/entitlements` response. */
+type EntitlementResponse = ProvenanceEnvelope<Entitlement>;
+
+type RoomRuntimeState = "discovered" | "pending_bootstrap" | "connecting" | "active" | "degraded" | "ended" | "closed";
+
+type LiveEventType = "chat" | "gift" | "member" | "like" | "social" | "roomUser" | "control" | "envelope" | "goodyBag" | "subscribe" | "linkMicBattle" | "linkMicArmies" | "hourlyRank" | "liveStart" | "unknown";
+interface ImageData {
+    urls: string[];
+    uri: string | null;
+    width: number | null;
+    height: number | null;
+}
+interface TextData {
+    displayType: string;
+    defaultPattern: string;
+}
+interface CommonMessageData {
+    method: string;
+    msgId: string;
+    roomId: string;
+    createTime: string;
+    logId: string;
+    displayText: TextData | null;
+}
+/**
+ * One of the user's live badges (D2.15). TikTok leads a feed row with the viewer's level/grade badge
+ * and any subscriber/fans badge; the level/tier is encoded in the badge ARTWORK
+ * (`grade_badge_icon_lite_lv15…`, `fans_badge_icon_lv1…`), so `imageUrl` is the icon a client renders
+ * — never a level integer we would have to infer. `type` is TikTok's own badge-kind discriminator
+ * (observed 20 = grade/level, 30 = fans/subscriber) carried verbatim for ordering/styling.
+ */
+interface LiveUserBadge {
+    type: number;
+    imageUrl: string;
+}
+interface UserData {
+    userId: string;
+    nickname: string;
+    uniqueId: string;
+    secUid: string;
+    verified: boolean;
+    avatar: ImageData | null;
+    /** Level/grade and subscriber badges, in TikTok's own order; empty when the frame carried none. */
+    badges: LiveUserBadge[];
+}
+interface GiftDetailsData {
+    id: string;
+    giftName: string;
+    describe: string;
+    diamondCount: number;
+    giftType: number;
+    combo: boolean;
+    image: ImageData | null;
+    previewImage: ImageData | null;
+}
+interface ChatMessageData {
+    common: CommonMessageData | null;
+    user: UserData | null;
+    comment: string;
+}
+interface GiftMessageData {
+    common: CommonMessageData | null;
+    user: UserData | null;
+    toUser: UserData | null;
+    giftId: string;
+    fanTicketCount: number;
+    groupCount: number;
+    repeatCount: number;
+    comboCount: number;
+    repeatEnd: boolean;
+    groupId: string;
+    logId: string;
+    isStreaking: boolean;
+    isCompleted: boolean;
+    gift: GiftDetailsData | null;
+}
+interface MemberMessageData {
+    common: CommonMessageData | null;
+    user: UserData | null;
+    operator: UserData | null;
+    action: number;
+    memberCount: number;
+    actionDescription: string;
+    userId: string;
+}
+interface LikeMessageData {
+    common: CommonMessageData | null;
+    user: UserData | null;
+    likeCount: number;
+    totalLikeCount: number;
+    color: number;
+}
+type SocialType = "follow" | "share" | "other";
+interface SocialMessageData {
+    common: CommonMessageData | null;
+    user: UserData | null;
+    socialType: SocialType;
+    action: string;
+    shareType: string;
+    shareTarget: string;
+    followCount: number;
+    shareDisplayStyle: string;
+    shareCount: number;
+    signature: string;
+    signatureVersion: string;
+    showDurationMs: string;
+    displayType: string | null;
+}
+interface ContributorData {
+    coinCount: number;
+    rank: number;
+    delta: string;
+    user: UserData | null;
+}
+interface RoomUserMessageData {
+    common: CommonMessageData | null;
+    viewerCount: number;
+    totalUser: number;
+    popularity: string;
+    anonymous: string;
+    popStr: string;
+    topViewers: ContributorData[];
+    seats: ContributorData[];
+}
+type ControlActionType = "STREAM_PAUSED" | "STREAM_UNPAUSED" | "STREAM_ENDED" | "STREAM_SUSPENDED" | "UNKNOWN";
+interface ControlExtraData {
+    banInfoUrl: string;
+    reasonNo: string;
+    title: TextData | null;
+    violationReason: TextData | null;
+    content: TextData | null;
+    gotItButton: TextData | null;
+    banDetailButton: TextData | null;
+    source: string;
+}
+interface ControlMessageData {
+    common: CommonMessageData | null;
+    action: ControlActionType;
+    actionCode: number;
+    isStreamEnd: boolean;
+    tips: string;
+    floatStyle: number;
+    floatText: TextData | null;
+    perceptionAudienceText: TextData | null;
+    extra: ControlExtraData | null;
+}
+interface EnvelopeInfo {
+    envelopeId: string;
+    businessType: number;
+    envelopeIdc: string;
+    sendUserName: string;
+    diamondCount: number;
+    peopleCount: number;
+    unpackAt: number;
+    sendUserId: string;
+    createAt: string;
+    roomId: string;
+    followShowStatus: number;
+    skinId: number;
+}
+interface EnvelopeMessageData {
+    display: number;
+    envelopeInfo: EnvelopeInfo | null;
+}
+interface GoodyBagMessageData {
+    roomId: string;
+    goodyBagId: string;
+    biz: string;
+    diamondCount: number;
+    peopleCount: number;
+    countDownMinutes: number;
+    unpackAt: number;
+    joinedHeadcount: number;
+    participateMethod: string;
+    participateMethodContent: string;
+    participateThresholdSelected: string | null;
+}
+/** A new/renewed channel subscription (WebcastSubNotifyMessage) — a direct monetization signal. */
+interface SubscribeMessageData {
+    common: CommonMessageData | null;
+    user: UserData | null;
+    /** Consecutive months the user has been subscribed (the headline value). */
+    subMonth: number;
+    /** TikTok's subscribe-type discriminator (new vs renew vs gifted), carried verbatim. */
+    subscribeType: number;
+    /** Prior subscription status code, verbatim. */
+    oldSubscribeStatus: number;
+    /** Current subscription status code, verbatim. */
+    subscribingStatus: number;
+    /** UI exhibition-type code, verbatim. */
+    exhibitionType: number;
+}
+/** One creator on a PK/LinkMic battle roster (WebcastLinkMicBattle → battleUsers). */
+interface LinkMicBattleParticipant {
+    user: UserData | null;
+}
+/** The start of a PK / versus battle — who is competing (WebcastLinkMicBattle). */
+interface LinkMicBattleData {
+    participants: LinkMicBattleParticipant[];
+}
+/** One supporter "army" behind a host in a live PK, with its running score. */
+interface LinkMicArmiesGroup {
+    /** The team's current battle points (the live PK scoreboard value). */
+    points: number;
+    /** Supporters counted into this team's points. */
+    users: UserData[];
+}
+/** One host's side of a PK battle (WebcastLinkMicArmies → battleItems). */
+interface LinkMicArmiesTeam {
+    hostUserId: string;
+    groups: LinkMicArmiesGroup[];
+}
+/** Live PK battle status + per-side scores (WebcastLinkMicArmies) — the running versus scoreboard. */
+interface LinkMicArmiesData {
+    /** TikTok battle-status code (e.g. in-progress vs ended), carried verbatim. */
+    battleStatus: number;
+    teams: LinkMicArmiesTeam[];
+}
+/** The room's hourly-rank standing (WebcastHourlyRankMessage). */
+interface HourlyRankData {
+    /** Ranking board type key, verbatim. */
+    type: string;
+    /** Human-readable rank label TikTok renders (e.g. the rank position text). */
+    label: string;
+    /** Rank item id, verbatim (bigint-safe string). */
+    rankId: string;
+    /** Rank item colour token, verbatim. */
+    colour: string;
+}
+interface RawLiveEventPayload {
+    messageType: string;
+    msgId: string;
+    msgType: number;
+    offset: string;
+    isHistory: boolean;
+    payloadBase64: string;
+    score?: number;
+    decodeError?: string;
+    /**
+     * Fields the decoder recognised but refused to read because their wire type no longer matches
+     * what our accessor expects — i.e. TikTok reshaped that field. The message still decodes (the
+     * field is skipped rather than misread, which would desync everything after it), so this is the
+     * ONLY signal that the value is missing rather than genuinely absent.
+     *
+     * It exists because the alternative is silent: a reshaped `diamondCount` would otherwise produce
+     * a perfectly-shaped gift worth 0 diamonds, feeding whale rollups and alert thresholds with
+     * zeroes and tripping no alarm. Each entry is `"<decoder>.<fieldNo>: expected wire N, got M"`.
+     */
+    decodeWarnings?: string[];
+}
+interface ChatLiveEventPayload extends RawLiveEventPayload {
+    decoded: ChatMessageData;
+}
+interface GiftLiveEventPayload extends RawLiveEventPayload {
+    decoded: GiftMessageData;
+}
+interface MemberLiveEventPayload extends RawLiveEventPayload {
+    decoded: MemberMessageData;
+}
+interface LikeLiveEventPayload extends RawLiveEventPayload {
+    decoded: LikeMessageData;
+}
+interface SocialLiveEventPayload extends RawLiveEventPayload {
+    decoded: SocialMessageData;
+}
+interface RoomUserLiveEventPayload extends RawLiveEventPayload {
+    decoded: RoomUserMessageData;
+}
+interface ControlLiveEventPayload extends RawLiveEventPayload {
+    decoded: ControlMessageData;
+}
+interface EnvelopeLiveEventPayload extends RawLiveEventPayload {
+    viewerCountSnapshot?: number | null;
+    decoded: EnvelopeMessageData;
+}
+interface GoodyBagLiveEventPayload {
+    messageType: "GoodyBagRoomResponse";
+    source: "mobile-api";
+    fetchedAt: string;
+    score: number;
+    viewerCountSnapshot?: number | null;
+    decoded: GoodyBagMessageData;
+}
+interface SubscribeLiveEventPayload extends RawLiveEventPayload {
+    decoded: SubscribeMessageData;
+}
+interface LinkMicBattleLiveEventPayload extends RawLiveEventPayload {
+    decoded: LinkMicBattleData;
+}
+interface LinkMicArmiesLiveEventPayload extends RawLiveEventPayload {
+    decoded: LinkMicArmiesData;
+}
+interface HourlyRankLiveEventPayload extends RawLiveEventPayload {
+    decoded: HourlyRankData;
+}
+/**
+ * LT1.5 — a synthetic "creator went live" marker emitted by stream-worker when a room transitions to
+ * `active` (it is NOT decoded from a TikTok frame). Distinct `type` (not `control`, which is also the
+ * session-END marker) so an alert rule can target "went live" without also firing on "ended". Its
+ * `roomState` is `"active"` and it is deliberately never `isStreamEnd`, so the history session-end
+ * consumer ignores it.
+ */
+interface LiveStartMessageData {
+    /** ISO instant the room was observed to transition to active. */
+    startedAt: string;
+}
+interface LiveStartLiveEventPayload extends RawLiveEventPayload {
+    decoded: LiveStartMessageData;
+}
+interface UnknownLiveEventPayload extends RawLiveEventPayload {
+    decoded?: never;
+}
+interface LiveEventPayloadByType {
+    chat: ChatLiveEventPayload;
+    gift: GiftLiveEventPayload;
+    member: MemberLiveEventPayload;
+    like: LikeLiveEventPayload;
+    social: SocialLiveEventPayload;
+    roomUser: RoomUserLiveEventPayload;
+    control: ControlLiveEventPayload;
+    envelope: EnvelopeLiveEventPayload;
+    goodyBag: GoodyBagLiveEventPayload;
+    subscribe: SubscribeLiveEventPayload;
+    linkMicBattle: LinkMicBattleLiveEventPayload;
+    linkMicArmies: LinkMicArmiesLiveEventPayload;
+    hourlyRank: HourlyRankLiveEventPayload;
+    liveStart: LiveStartLiveEventPayload;
+    unknown: UnknownLiveEventPayload;
+}
+
+interface TokTikResponse {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}
+type TokTikFetch = (url: string, init: {
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<TokTikResponse>;
+interface TokTikClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: TokTikFetch;
+}
+/**
+ * A non-2xx answer from the API.
+ *
+ * The status is deliberately surfaced rather than folded into a generic failure: the four the API
+ * uses to say something actionable each need a different reaction from the caller, and swallowing
+ * them is the failure mode this SDK exists to prevent.
+ *
+ * - `401` bad/expired key · `403` the key lacks the scope this resource is sold under
+ * - `402` out of credits — buying more is the only fix; retrying will not help
+ * - `429` rate limited — retry after backing off
+ */
+declare class TokTikApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly requestId: string | undefined;
+    constructor(status: number, code: string | undefined, requestId: string | undefined, message: string);
+    /** True when retrying the identical request could plausibly succeed. */
+    get retryable(): boolean;
+    /** Out of credits. Distinct from `403`: the key is valid and scoped, the wallet is empty. */
+    get isPaymentRequired(): boolean;
+    /** The key is missing the scope this endpoint is sold under (or is not a data-plane key at all). */
+    get isForbidden(): boolean;
+    get isUnauthorized(): boolean;
+    get isRateLimited(): boolean;
+}
+declare function buildQuery(parameters?: Record<string, unknown>): string;
+/** Shared request plumbing. Deliberately has no retries, caching, or credential storage. */
+declare class HttpTransport {
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private readonly apiKey;
+    constructor(options: TokTikClientOptions);
+    get<T>(path: string, parameters?: Record<string, unknown>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * For endpoints that answer with something other than JSON (today: the CSV export download).
+     * Errors are still parsed as JSON, because a failure is always the JSON error envelope.
+     */
+    getText(path: string, parameters?: Record<string, unknown>): Promise<string>;
+    private request;
+}
+
+/**
+ * Every option name below is transcribed from the route's own Fastify schema in
+ * `apps/platform-api/src/routes/**`. Those schemas set `additionalProperties: false`, so an invented
+ * name is a hard 400 — not a silently ignored extra. Do not add a field here without reading the
+ * matching schema first.
+ */
+/** `/v1/live/sessions` — `paginationProperties`: `cursor` (ISO date-time keyset) + `limit`. */
+interface LiveSessionsOptions {
+    creatorUniqueId?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface CursorPageOptions {
+    cursor?: string;
+    limit?: number;
+}
+/** `/v1/rankings/official` — `board` is REQUIRED. */
+interface OfficialRankingOptions {
+    board: string;
+    region?: string;
+    limit?: number;
+}
+/** `/v1/rankings/movers` — `board` is REQUIRED; `limit` (1–99, default 20) caps each of gainers/losers. */
+interface RankMoversOptions {
+    board: string;
+    region?: string;
+    limit?: number;
+}
+/** `/v1/rankings/history` — `board` is REQUIRED; `limit` counts PERIODS (1–24), not rows. */
+interface RankingHistoryOptions {
+    board: string;
+    region?: string;
+    limit?: number;
+    cursor?: string;
+    leagueTier?: string;
+}
+/** `/v1/rankings/gaming/games` — the only filter is `region` (a BUCKET key); omit it for the server default. */
+interface GamingGamesOptions {
+    region?: string;
+}
+/** `/v1/creators` — search only takes `q` + `limit`. No cursor. */
+interface CreatorListOptions {
+    q?: string;
+    limit?: number;
+    region?: string;
+    minFollowers?: number;
+    liveNow?: boolean;
+    /** `followers` (default) or `rank` (the region's current Daily board order). */
+    sort?: "followers" | "rank";
+    cursor?: string;
+}
+/** `/v1/creators/:uid/changes` — `limit` ONLY; this route has no cursor. */
+interface CreatorChangesOptions {
+    limit?: number;
+}
+/** `/v1/trends` — `type` is an enum of exactly these two. */
+interface TrendOptions {
+    region?: string;
+    type?: "hashtag" | "sound";
+}
+/** Gifter routes are scoped to a discrete observation window (24h/7d/30d, default 7d), not a cursor. */
+interface GifterWindowOptions {
+    window?: GifterWindow;
+    limit?: number;
+}
+interface GifterListOptions extends GifterWindowOptions {
+    creator?: string;
+}
+interface CommentOptions extends CursorPageOptions {
+    parentCommentId?: string;
+}
+/** `POST /v1/exports` body. `dataset`/`format` are REQUIRED single-value enums today. */
+interface ExportCreateInput {
+    dataset: "live_sessions";
+    format: "csv";
+    rangeDays?: number;
+}
+/** Mirrors `DeveloperUsageResponse` in `apps/platform-api/src/services/usage/usage-service.ts`. */
+interface DeveloperUsage {
+    period: string;
+    balance: {
+        remaining: number;
+        spent: number;
+    };
+    items: Array<{
+        id: string;
+        apiKeyId: string | null;
+        apiKeyPrefix: string | null;
+        apiKeyLabel: string | null;
+        operation: string;
+        creditDelta: number;
+        createdAt: string;
+    }>;
+}
+interface UsageOptions {
+    /** First day of a month: `YYYY-MM-01`. */
+    period?: string;
+    limit?: number;
+}
+/** `live:read` + `live:stream` — LIVE sessions, per-creator performance, realtime handshake token. */
+declare class LiveResource {
+    private readonly http;
+    constructor(http: HttpTransport);
+    listSessions(options?: LiveSessionsOptions): Promise<ProvenanceEnvelope<LiveSessionListResponse>>;
+    getSession(id: string): Promise<ProvenanceEnvelope<LiveSessionRecord>>;
+    creatorPerformance(creatorUniqueId: string, options?: CursorPageOptions): Promise<ProvenanceEnvelope<LiveCreatorPerformanceListResponse>>;
+    /**
+     * Mint a short-lived realtime handshake token (D2.3). `client.live.stream()` calls this for you —
+     * use it directly only when driving the WebSocket yourself.
+     */
+    streamToken(): Promise<{
+        token: string;
+        tokenType: "Bearer";
+        expiresIn: number;
+        wsUrl: string;
+    }>;
+    /**
+     * LIVE video playback sources for a creator who is live now (D2.12). `live:stream`, not
+     * `live:read` — this is the video, not the metrics. The customer's runtime fetches the stream
+     * itself from TikTok's CDN. `status` is `live` (with `hlsUrl`/`flvUrl`), `no_playback`, or
+     * `offline`; a room still being resolved answers `202` (poll again).
+     */
+    playback(creatorUniqueId: string): Promise<LivePlaybackResponse>;
+}
+/** `GET /v1/live/creators/:uid/playback` — polymorphic by `status`. */
+interface LivePlaybackResponse {
+    status: "live" | "no_playback" | "offline";
+    roomId?: string | null;
+    title?: string | null;
+    nickname?: string | null;
+    hlsUrl?: string | null;
+    flvUrl?: string | null;
+    expiresAt?: string | null;
+    startedAt?: string | null;
+    avatarUrl?: string | null;
+    verified?: boolean;
+    followerCount?: number | null;
+    region?: string | null;
+    source?: string;
+    cached?: boolean;
+    message?: string | null;
+}
+/**
+ * `rank:read`. Provenance-enveloped: `rankings-service.ts` returns
+ * `ProvenanceEnvelope<OfficialRankingResponse>` — `{ data: { board }, provenance }`.
+ */
+declare class RankingsResource {
+    private readonly http;
+    constructor(http: HttpTransport);
+    /** `board` is required by the server; there is no default. */
+    official(options: OfficialRankingOptions): Promise<ProvenanceEnvelope<OfficialRankingResponse>>;
+    /**
+     * Region "movers" — the creators whose rank changed most since the board's previous period, split
+     * into `gainers` (moved up) and `losers` (moved down), each biggest-move-first and capped by
+     * `limit` (1–99, default 20). Identity is masked by your plan tier exactly as `official`.
+     */
+    movers(options: RankMoversOptions): Promise<ProvenanceEnvelope<RankMoversResponse>>;
+    /**
+     * Retained periods of a board, newest first — the source for a rank trend.
+     *
+     * `limit` counts PERIODS (1–24, default 12), not rows: each period carries the whole 99-rank
+     * board. Page with `cursor` (opaque). One request costs one credit regardless of how many
+     * periods come back.
+     */
+    history(options: RankingHistoryOptions): Promise<ProvenanceEnvelope<RankingHistoryResponse>>;
+    /**
+     * The regions a board can be read for, with each one's coverage and the boards it has captured.
+     *
+     * Call this instead of guessing: boards are keyed by BUCKET — `US+`, `MENA`, `LATAM`, `DE+` — and
+     * an ISO country code like `US` or `DE` matches no board at all, so it comes back coverage-gated
+     * rather than empty. The list reflects what has actually been captured, not what is configured.
+     *
+     * Each region also carries `notOfferedBoards`: the boards proven absent from TikTok's product
+     * there. Hide or disable only those. A board missing from `boards` may simply be one we have not
+     * captured yet, and it still answers for itself with an honest `not-covered`.
+     */
+    regions(): Promise<ProvenanceEnvelope<RankingRegionsResponse>>;
+    /**
+     * The per-game gaming boards a region offers — the source for the `game` parameter of a
+     * `board: "gaming_game"` read on `official` (and `movers` / `history`). Pass `games[].gameKey`
+     * verbatim; never hardcode a game list (the R5.7 lesson applied to games).
+     *
+     * `status` is `offered` (readable now) or `not_offered` (a game TikTok has pulled). An empty
+     * `games` array is a valid answer, not an error: the region runs only the aggregate gaming board,
+     * so show no game selector. `region` is a BUCKET key exactly as `regions` reports; omit it to
+     * accept the server default.
+     */
+    games(options?: GamingGamesOptions): Promise<ProvenanceEnvelope<GamingGamesResponse>>;
+}
+/** `creator:read` — profile, change history, analysis. Videos live on `content` (`content:read`). */
+declare class CreatorsResource {
+    private readonly http;
+    constructor(http: HttpTransport);
+    /** Handle/name search. */
+    list(options?: CreatorListOptions): Promise<CreatorSearchResponse>;
+    get(uid: string): Promise<CreatorProfileResponse>;
+    changes(uid: string, options?: CreatorChangesOptions): Promise<CreatorChangesResponse>;
+    analysis(uid: string): Promise<CreatorAnalysisResponse>;
+    /** R4.5 — the same read in both directions; a real upstream walk bills the heavier SKU. */
+    following(uid: string, options?: CursorPageOptions): Promise<FollowListResponse>;
+    followers(uid: string, options?: CursorPageOptions): Promise<FollowListResponse>;
+}
+/** `content:read` — a creator's videos, one video, its comments. Sold separately from the profile. */
+declare class ContentResource {
+    private readonly http;
+    constructor(http: HttpTransport);
+    /** Takes no query parameters — the route declares no querystring schema and the service uses a
+     * fixed internal limit. (A param passed here would be silently ignored, not rejected, which is why
+     * an acceptance run cannot catch it — the route has no schema to reject against.) */
+    creatorVideos(uid: string): Promise<CreatorVideosResponse>;
+    /** D6.1 — the creator's active story tray, fetched fresh through the signed mobile path. Empty
+     * tray (never an error) when no signed credential is configured. */
+    creatorStories(uid: string): Promise<CreatorStoriesResponse>;
+    video(videoId: string): Promise<VideoDetailResponse>;
+    videoComments(videoId: string, options?: CommentOptions): Promise<VideoCommentsResponse>;
+}
+/** `gifter:read` — whale intelligence. Its own SKU, hence its own namespace. */
+declare class GiftersResource {
+    private readonly http;
+    constructor(http: HttpTransport);
+    list(options?: GifterListOptions): Promise<ProvenanceEnvelope<GifterListResponse>>;
+    get(gifterKey: string, options?: GifterWindowOptions): Promise<ProvenanceEnvelope<GifterProfileResponse>>;
+    forCreator(handle: string, options?: GifterWindowOptions): Promise<ProvenanceEnvelope<CreatorGiftersResponse>>;
+}
+/** `trend:read` */
+declare class TrendsResource {
+    private readonly http;
+    constructor(http: HttpTransport);
+    /** Note: this route takes no `limit`. */
+    list(options?: TrendOptions): Promise<TrendsResponse>;
+}
+/** `export` — async bulk extracts. */
+declare class ExportsResource {
+    private readonly http;
+    constructor(http: HttpTransport);
+    /** Takes no query parameters. */
+    list(): Promise<ExportJobListResponse>;
+    create(input: ExportCreateInput): Promise<ExportJob>;
+    get(id: string): Promise<ExportJob>;
+    /**
+     * The finished extract itself — **`text/csv`, not JSON**, returned as a string. Parsing it as JSON
+     * (as an earlier version of this SDK did) silently yields `undefined`.
+     */
+    download(id: string): Promise<string>;
+}
+/** `keys:manage` — what this key may do, and what it has spent. */
+declare class AccountResource {
+    private readonly http;
+    constructor(http: HttpTransport);
+    entitlements(options?: {
+        period?: string;
+    }): Promise<EntitlementResponse>;
+    /** Not provenance-enveloped — `usage-service.ts` returns this shape directly. */
+    usage(options?: UsageOptions): Promise<DeveloperUsage>;
+}
+
+/** Minimal WebSocket surface, so the SDK works on browser `WebSocket` and Node's `ws` alike. */
+interface RealtimeSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+/**
+ * Opens the WebSocket. The token MUST travel in a header or the `Sec-WebSocket-Protocol`
+ * subprotocol — never the query string, where it would leak into access logs and browser history.
+ * The default implementation uses the subprotocol form, which is the only one a browser
+ * `WebSocket` can set.
+ */
+type RealtimeSocketFactory = (url: string, token: string) => RealtimeSocket;
+interface RealtimeHandlers {
+    onEvent?: (frame: RealtimeEventFrame) => void;
+    onStatus?: (frame: RealtimeStatusFrame) => void;
+    onError?: (error: RealtimeErrorFrame | Error) => void;
+    /** Fired after a reconnect once every subscription has been re-sent. */
+    onReconnect?: (attempt: number) => void;
+}
+interface RealtimeStreamOptions {
+    /** Cap on reconnect attempts. `Infinity` (default) keeps trying forever with a bounded delay. */
+    maxReconnectAttempts?: number;
+    baseReconnectDelayMs?: number;
+    maxReconnectDelayMs?: number;
+    socketFactory?: RealtimeSocketFactory;
+    /** Test seams. */
+    setTimeoutImpl?: (handler: () => void, ms: number) => unknown;
+    clearTimeoutImpl?: (handle: unknown) => void;
+    random?: () => number;
+}
+interface TokenMinter {
+    (): Promise<{
+        token: string;
+        wsUrl: string;
+    }>;
+}
+/**
+ * A live subscription set over one WebSocket.
+ *
+ * Owns three things the caller should not have to: token lifetime (re-minted per connection, so an
+ * expiry mid-stream costs a reconnect rather than a dead socket), reconnection with exponential
+ * backoff + jitter (a fleet reconnecting in lockstep after a gateway restart is a self-inflicted
+ * thundering herd), and subscription resume — the gateway keeps no per-connection memory, so the
+ * new socket must re-subscribe or the caller silently receives nothing.
+ */
+declare class RealtimeStream {
+    private readonly mintToken;
+    private readonly handlers;
+    private socket;
+    private readonly creators;
+    private closed;
+    private attempt;
+    /** True only between `onopen` and the socket going away — `send()` before this throws in real runtimes. */
+    private opened;
+    private reconnectTimer;
+    /**
+     * Bumped by `close()` and by each `open()`. An `open()` that started before the bump finds its
+     * generation stale and discards the socket it just created — otherwise `close()` racing an
+     * in-flight `open()` leaves a live, unreferenced socket behind (still billed, never closed).
+     */
+    private generation;
+    private readonly options;
+    constructor(mintToken: TokenMinter, handlers: RealtimeHandlers, options?: RealtimeStreamOptions);
+    /** Creators currently subscribed (survives reconnects). */
+    get subscriptions(): string[];
+    /** True only once the socket is OPEN and accepting frames — not merely constructed. */
+    get isConnected(): boolean;
+    connect(creatorIds?: string[]): Promise<void>;
+    subscribe(creatorId: string): void;
+    unsubscribe(creatorId: string): void;
+    /** Stop for good. Cancels reconnection — this is not a transient drop. */
+    close(): void;
+    private send;
+    private open;
+    private scheduleReconnect;
+}
+/** Mirrors the gateway's own normalisation so the SDK and server agree on subscription identity. */
+declare function normalizeCreatorId(value: string): string;
+
+/**
+ * Typed client for the TokTik Developer API.
+ *
+ * ```ts
+ * const client = new TokTikClient({ apiKey: process.env.TOKTIK_API_KEY! });
+ * const board = await client.rankings.official({ board: "hourly", region: "VN" });
+ * const stream = await client.live.stream(["@creator"], { onEvent: (e) => console.log(e.event) });
+ * ```
+ *
+ * Most data methods return the provenance envelope **unchanged** — `data` alongside the `provenance`
+ * block describing how fresh the answer is and how it was obtained. The SDK never strips it, because
+ * for observed (rather than officially published) data that context is part of the answer.
+ * `exports.*` and `account.usage()` are the documented exceptions: the server does not envelope them.
+ */
+declare class TokTikClient {
+    private readonly http;
+    readonly live: LiveResource & {
+        /** Open a realtime stream. Mints its own handshake token and keeps it fresh across reconnects. */
+        stream: (creatorIds: string[], handlers: RealtimeHandlers, options?: RealtimeStreamOptions) => Promise<RealtimeStream>;
+    };
+    readonly rankings: RankingsResource;
+    readonly creators: CreatorsResource;
+    readonly content: ContentResource;
+    readonly gifters: GiftersResource;
+    readonly trends: TrendsResource;
+    readonly exports: ExportsResource;
+    readonly account: AccountResource;
+    constructor(options: TokTikClientOptions);
+    /** @deprecated Use `client.live.listSessions()`. */
+    listLiveSessions(options?: LiveSessionsOptions): Promise<ProvenanceEnvelope<LiveSessionListResponse>>;
+    /** @deprecated Use `client.live.getSession()`. */
+    getLiveSession(id: string): Promise<ProvenanceEnvelope<LiveSessionRecord>>;
+    /** @deprecated Use `client.live.creatorPerformance()`. */
+    listCreatorPerformance(creatorUniqueId: string, options?: CursorPageOptions): Promise<ProvenanceEnvelope<LiveCreatorPerformanceListResponse>>;
+}
+
+export { AccountResource, ContentResource, CreatorsResource, ExportsResource, GiftersResource, HttpTransport, LiveResource, RankingsResource, RealtimeStream, TokTikApiError, TokTikClient, TrendsResource, buildQuery, normalizeCreatorId };
+export type { CommentOptions, CreatorChangesOptions, CreatorListOptions, CursorPageOptions, DeveloperUsage, ExportCreateInput, GamingGamesOptions, GifterListOptions, GifterWindowOptions, LivePlaybackResponse, LiveSessionsOptions, OfficialRankingOptions, RankMoversOptions, RankingHistoryOptions, RealtimeHandlers, RealtimeSocket, RealtimeSocketFactory, RealtimeStreamOptions, TokTikClientOptions, TokTikFetch, TokTikResponse, TrendOptions, UsageOptions };