@flitt/api 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0 — 2026-09-28
+
+First release.
+
+- `Flitt` client for the Public API v1: usage, servers, players, firewall (settings, rules, blocks), in-game commands, Discord account linking.
+- `FlittVotes` client for the Vote API: check, claim (idempotent), list, top voters, server info, stats, reviews.
+- `verifyWebhook()` for signed Flitt webhooks (HMAC-SHA256, timestamp tolerance, replay hook).
+- Async iterators for paginated endpoints (`listAll`).
+- Timeouts, retries with exponential backoff and `Retry-After`, typed errors, rate-limit state.
+- ESM + CommonJS builds, TypeScript types, zero dependencies, Node.js 20+.

package/LICENSE

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

package/README.md

@@ -0,0 +1,277 @@
+# @flitt/api
+
+Official TypeScript / JavaScript client for the [Flitt](https://flitt.me) **Public API** and **Vote API**: servers, players, anti-VPN firewall, Discord account linking, in-game commands, votes and webhooks for FiveM, Garry's Mod and Minecraft servers.
+
+- **Zero dependencies**, ESM + CommonJS, full TypeScript types.
+- Runs on **Node.js 20+**, Deno, Bun, Cloudflare Workers and any runtime with `fetch`.
+- **Safe by default**: HTTPS only, key never logged, no redirect follow, browser guard, typed errors.
+- **Resilient**: per-request timeout, automatic retries with exponential backoff, `Retry-After` honoured, idempotent vote claims.
+
+```bash
+npm install @flitt/api
+# or: pnpm add @flitt/api · yarn add @flitt/api · bun add @flitt/api
+```
+
+## Quick start
+
+```ts
+import { Flitt } from "@flitt/api";
+
+const flitt = new Flitt({ apiKey: process.env.FLITT_API_KEY });
+
+const { data: servers } = await flitt.servers.list();
+for (const server of servers) {
+  console.log(`${server.name}: ${server.playersOnline} players (${server.status})`);
+}
+```
+
+CommonJS works too:
+
+```js
+const { Flitt } = require("@flitt/api");
+```
+
+Create your API key in **Dashboard → Profile → API** on [flitt.me](https://flitt.me). It starts with `flt_` and is shown once. If `apiKey` is omitted, the client reads the `FLITT_API_KEY` environment variable.
+
+> **Keep your key on a server.** Anyone who reads it can act on your servers (bans, firewall, commands). The client refuses to run in a web page unless you pass `dangerouslyAllowBrowser: true`.
+
+## Quotas
+
+| Plan | Public API | Vote API |
+|---|---|---|
+| Freemium | 1,000 requests / month | 120 requests / minute per token |
+| Premium | 20,000 requests / month | 120 requests / minute per token |
+| Enterprise | Unlimited | 120 requests / minute per token |
+
+The quota state of the last response is available on `flitt.rateLimit` (`{ limit, remaining, reset }`, `null` values meaning unlimited), or through the `onRateLimit` callback.
+
+## Public API
+
+Every method returns a Promise and throws a typed error on failure (see [Errors](#errors)).
+
+### Account
+
+```ts
+const usage = await flitt.usage.get();
+// { enabled, plan, limitPerMonth, usedLast30d, remaining, resetAt }
+```
+
+### Servers
+
+```ts
+const page = await flitt.servers.list({ page: 1, limit: 25 }); // { data, pagination }
+const server = await flitt.servers.get("srv_123");            // ip/port hidden for the VIEWER role
+
+for await (const s of flitt.servers.listAll()) {
+  // every server you own or are a member of, page after page
+}
+```
+
+### Players
+
+```ts
+const { players } = await flitt.players.list("srv_123", { status: "online", limit: 50 });
+const player = await flitt.players.get("srv_123", "76561198000000000"); // Flitt id or external id
+
+for await (const p of flitt.players.listAll("srv_123", { status: "all" })) {
+  console.log(p.name, p.totalPlaySeconds);
+}
+```
+
+### Firewall (anti-VPN)
+
+Changes need the **OWNER** or **ADMIN** role on the server.
+
+```ts
+await flitt.firewall.update("srv_123", { enabled: true, blockVpn: true, kickMessage: "VPN not allowed" });
+
+// One rule, or up to 100 in one call. Partial success is possible:
+const result = await flitt.firewall.rules.create("srv_123", [
+  { action: "DENY", kind: "IDENTIFIER", value: "76561198000000000", note: "Cheater" },
+  { action: "DENY", kind: "COUNTRY", value: "XX" },
+]);
+for (const e of result.errors) console.warn(`rule ${e.index}: ${e.code} ${e.message}`);
+
+const { rules } = await flitt.firewall.rules.list("srv_123", { action: "DENY", q: "7656" });
+await flitt.firewall.rules.delete("srv_123", rules[0].id);
+await flitt.firewall.rules.deleteMany("srv_123", { kind: "COUNTRY" }); // refuses an empty filter
+const blocked = await flitt.firewall.blocks("srv_123", { limit: 20 });
+```
+
+### In-game commands
+
+Queued for the Flitt addon of the server. `chat` and `notify` need the **EDITOR** role, the others **ADMIN**. Pass `waitMs` (max 15000) to wait for the addon's answer.
+
+```ts
+await flitt.commands.chat("srv_123", "Restart in 5 minutes!");
+await flitt.commands.notify("srv_123", "76561198000000000", "Your VIP is active");
+await flitt.commands.kick("srv_123", "76561198000000000", "AFK");
+const res = await flitt.commands.ban("srv_123", "76561198000000000", { reason: "RDM", durationSeconds: 86_400 }, { waitMs: 5000 });
+console.log(res.result?.ok, res.result?.output);
+await flitt.commands.unban("srv_123", "76561198000000000");
+await flitt.commands.setGroup("srv_123", "76561198000000000", "vip");            // ULX, SAM, CAMI, ace groups, LuckPerms…
+await flitt.commands.setGroup("srv_123", "76561198000000000", "vip", { add: false });
+const { players } = await flitt.commands.groups("srv_123");                       // current groups of online players
+```
+
+Commands are **not retried automatically**: a retry could run a ban twice.
+
+### Discord account linking
+
+The same flow as the Flitt bot's `/link`, for your own bot.
+
+```ts
+const { code } = await flitt.discord.createLinkCode("123456789012345678");
+// the player types `!flitt CODE` in game (GMod / FiveM) or `/flitt link CODE` (Minecraft)
+
+const links = await flitt.discord.findLinks({ discordId: "123456789012345678" });
+await flitt.discord.link("srv_123", { discordId: "123456789012345678", externalId: "76561198000000000" });
+await flitt.discord.unlink("srv_123", "76561198000000000");
+await flitt.discord.setModule("srv_123", true); // API-only setups, without the Flitt bot
+```
+
+## Vote API
+
+For servers **without the Flitt addon**: your own script checks that a player voted, claims the vote exactly once, then gives the reward. One token per server, created in **Dashboard → your server → Votes → Vote API** (starts with `flv_`, shown once). Default env variable: `FLITT_VOTE_TOKEN`.
+
+```ts
+import { FlittVotes } from "@flitt/api";
+
+const votes = new FlittVotes({ token: process.env.FLITT_VOTE_TOKEN });
+
+const claim = await votes.claim({ player: "Alex_RP" });
+if (claim.status === "CLAIMED_NOW") {
+  giveReward("Alex_RP");
+  // Premium / Enterprise servers: bonus rewards won in the draw
+  for (const bonus of claim.rewards ?? []) giveBonus("Alex_RP", bonus.id);
+}
+```
+
+Identify the player with **exactly one** of `player`, `steamId`, `discordId`, `license`, `uuid`, `ip` or `voteId`.
+
+| Method | Description |
+|---|---|
+| `check(identity)` | `CLAIMABLE`, `CLAIMED` or `NOT_FOUND`, plus `nextVoteInMinutes` |
+| `claim(identity, { idempotencyKey? })` | Claims the oldest unclaimed vote (24 h window) |
+| `list({ since?, limit?, cursor? })` / `listAll()` | Recent votes, cursor pagination (30 days max) |
+| `top({ period?, limit? })` | Top voters: `current_month`, `last_month`, `all_time` or `YYYY-MM` |
+| `server({ includeStats? })` | Status, vote counters, ranking, reviews |
+| `stats()` | Daily / weekly / monthly votes, views and join clicks |
+| `reviews({ limit?, cursor?, sort? })` | Published reviews |
+
+`claim()` always sends an `Idempotency-Key`, so an automatic retry after a network error can never claim two votes. Pass your own key (for example `${player}:${hour}`) to make your own retries safe as well.
+
+## Webhooks
+
+Verify that a webhook really comes from Flitt before trusting it. Pass the **raw** body (not re-serialised JSON) and the secret shown when you created the webhook.
+
+```ts
+import express from "express";
+import { verifyWebhook, FlittWebhookError } from "@flitt/api";
+
+const app = express();
+const seen = new Map<string, number>(); // use Redis or your database in production
+
+app.post("/flitt-webhook", express.raw({ type: "application/json" }), async (req, res) => {
+  try {
+    const event = await verifyWebhook({
+      payload: req.body,               // Buffer
+      headers: req.headers,
+      secret: process.env.FLITT_WEBHOOK_SECRET!,
+      isReplay: (nonce) => {           // optional replay protection
+        if (seen.has(nonce)) return true;
+        seen.set(nonce, Date.now());
+        return false;
+      },
+    });
+    if (event.event === "server_down") console.log(`${event.server.name} is down`);
+    res.sendStatus(204);
+  } catch (err) {
+    res.sendStatus(err instanceof FlittWebhookError ? 400 : 500);
+  }
+});
+```
+
+With the Fetch API (Next.js route handlers, Workers, Deno, Bun):
+
+```ts
+export async function POST(request: Request) {
+  const event = await verifyWebhook({ payload: await request.text(), headers: request.headers, secret: process.env.FLITT_WEBHOOK_SECRET! });
+  return new Response(null, { status: 204 });
+}
+```
+
+The signature is HMAC-SHA256 of `timestamp.nonce.body`, compared in constant time; deliveries older than 5 minutes are refused (`toleranceSec`).
+
+## Errors
+
+All errors extend `FlittError`. API errors extend `FlittAPIError` and carry `status`, `code`, `message`, `details`, `method`, `path`, `rateLimit` and `retryAfterMs`. **They never contain your key.**
+
+| Class | When |
+|---|---|
+| `FlittConfigError` | Bad option or argument, detected before any request |
+| `FlittValidationError` | 400 invalid parameter |
+| `FlittAuthenticationError` | 401 missing, invalid or revoked key / token |
+| `FlittPermissionError` | 403 plan or role does not allow it |
+| `FlittNotFoundError` | 404 not found, or not yours |
+| `FlittConflictError` | 409 conflict (duplicate rule, inactive server…) |
+| `FlittRateLimitError` | 429 quota reached: see `retryAfterMs` / `rateLimit.reset` |
+| `FlittServerError` | 5xx temporary error on Flitt's side |
+| `FlittTimeoutError` | No response within `timeoutMs` |
+| `FlittConnectionError` | Network failure (DNS, TLS, reset…) |
+| `FlittAbortError` | Aborted through your `AbortSignal` |
+
+```ts
+import { FlittNotFoundError, FlittRateLimitError } from "@flitt/api";
+
+try {
+  await flitt.servers.get("srv_123");
+} catch (err) {
+  if (err instanceof FlittNotFoundError) console.log("Unknown server");
+  else if (err instanceof FlittRateLimitError) console.log(`Quota reached, retry in ${err.retryAfterMs} ms`);
+  else throw err;
+}
+```
+
+## Options
+
+```ts
+new Flitt({
+  apiKey: "flt_…",              // default: process.env.FLITT_API_KEY
+  baseUrl: "https://api.flitt.me",
+  timeoutMs: 15_000,           // per attempt
+  maxRetries: 2,               // idempotent requests: network errors, 408, 425, 5xx, short 429
+  maxRetryDelayMs: 30_000,     // longest single wait; a longer Retry-After is not waited for
+  fetch: customFetch,          // tests, proxies, instrumentation
+  userAgent: "my-bot/1.0",     // server-side only
+  onRateLimit: (rl) => metrics.gauge("flitt.remaining", rl.remaining ?? Infinity),
+  dangerouslyAllowBrowser: false,
+});
+```
+
+Every method also takes a last `options` argument: `{ signal?: AbortSignal, timeoutMs?: number, maxRetries?: number }`.
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 2000);
+await flitt.servers.list({}, { signal: controller.signal });
+```
+
+## Security
+
+- HTTPS only (HTTP is accepted for `localhost` during development); credentials, query strings and fragments in `baseUrl` are rejected.
+- Redirects are never followed, so the `Authorization` header cannot leak to another host.
+- Path segments are URL-encoded and dot segments are refused.
+- The key lives in a private class field: `console.log`, `util.inspect`, `JSON.stringify` and error objects never show it.
+- Keys are format-checked locally, so a vote token passed as an API key (or the reverse) fails before any request.
+- Responses larger than 32 MB are refused.
+
+Report a vulnerability: see [SECURITY.md](./SECURITY.md).
+
+## Links
+
+- API reference: https://flitt.me/docs/public-api
+- Support: https://flitt.me/dashboard/support · contact@flitt.me
+- Discord: https://discord.gg/DujRDRsrWD
+
+MIT © Flitt

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please do not open a public issue. Write to **contact@flitt.me** (subject "Security") or open a ticket from https://flitt.me/dashboard/support with the steps to reproduce. We acknowledge within 48 hours and do not pursue good-faith researchers.
+
+## Supported versions
+
+Security fixes are released for the latest major version of `@flitt/api`.
+
+## Handling your credentials
+
+- Public API keys (`flt_…`) and Vote API tokens (`flv_…`) are secrets. Keep them in environment variables or a secret manager, never in client-side code or a public repository.
+- If a key leaks, rotate it at once from the dashboard (Profile → API, or your server → Votes → Vote API).
+- This package never logs, prints or serialises your key, only sends it over HTTPS in the `Authorization` header, and never follows redirects.

package/dist/cjs/client.d.ts

@@ -0,0 +1,243 @@
+import { Transport, type FetchLike, type RequestOptions } from "./http.js";
+import type { AccountLink, CommandInput, CommandResult, DiscordModule, FirewallBlock, FirewallRuleBulkDelete, FirewallRuleCreateResult, FirewallRuleInput, FirewallRuleList, FirewallRuleQuery, FirewallSettings, FirewallSettingsUpdate, GroupList, LinkCode, PageParams, Player, PlayerList, PlayerStatusFilter, RateLimit, ReviewList, ReviewListParams, Server, ServerList, ServerSummary, TopVoters, TopVotersPeriod, Usage, VoteCheck, VoteClaim, VoteIdentity, VoteList, VoteListItem, VoteListParams, VoteServer, VoteStats } from "./types.js";
+export declare const DEFAULT_BASE_URL = "https://api.flitt.me";
+export type ClientOptions = {
+    /** API root, default `https://api.flitt.me`. HTTPS only (HTTP allowed for localhost). */
+    baseUrl?: string;
+    /** Per-attempt timeout in ms, default 15000. */
+    timeoutMs?: number;
+    /** Retries of idempotent requests on network errors, 5xx and short 429s. Default 2. */
+    maxRetries?: number;
+    /** Upper bound of a single wait between retries, in ms. Default 30000. */
+    maxRetryDelayMs?: number;
+    /** Custom fetch (tests, proxies, older runtimes). Default: global fetch. */
+    fetch?: FetchLike;
+    /** Replaces the default `flitt-api-js/<version>` User-Agent (server-side only). */
+    userAgent?: string;
+    /** Called with the quota state after every response that carries X-RateLimit-* headers. */
+    onRateLimit?: (rateLimit: RateLimit) => void;
+    /**
+     * Your key is a secret: anyone who reads it can act on your servers. The
+     * client refuses to run in a browser unless you set this to true (e.g. an
+     * internal tool where only you use the page).
+     */
+    dangerouslyAllowBrowser?: boolean;
+};
+export type FlittOptions = ClientOptions & {
+    /** Public API key (`flt_…`, Profile → API). Default: `process.env.FLITT_API_KEY`. */
+    apiKey?: string;
+};
+export type FlittVotesOptions = ClientOptions & {
+    /** Vote API token of one server (`flv_…`, Dashboard → server → Votes). Default: `process.env.FLITT_VOTE_TOKEN`. */
+    token?: string;
+};
+declare const INSPECT: unique symbol;
+/**
+ * Client of the Flitt Public API v1.
+ *
+ * ```ts
+ * import { Flitt } from "@flitt/api";
+ * const flitt = new Flitt({ apiKey: process.env.FLITT_API_KEY });
+ * const { data } = await flitt.servers.list();
+ * ```
+ */
+export declare class Flitt {
+    #private;
+    /** Your account's monthly quota. */
+    readonly usage: {
+        get(options?: RequestOptions): Promise<Usage>;
+    };
+    readonly servers: ServersResource;
+    readonly players: PlayersResource;
+    readonly firewall: FirewallResource;
+    readonly discord: DiscordResource;
+    readonly commands: CommandsResource;
+    constructor(options?: FlittOptions);
+    /** Quota state from the last response (`null` before the first request). */
+    get rateLimit(): RateLimit | null;
+    /** Never prints the key. */
+    toJSON(): {
+        client: string;
+        apiKey: string;
+    };
+    [INSPECT](): string;
+}
+declare class ServersResource {
+    private readonly http;
+    private readonly base;
+    constructor(http: Transport, base: string);
+    /** Servers you own or are a member of, newest first. `limit`: 1 to 100 (default 25). */
+    list(params?: PageParams, options?: RequestOptions): Promise<ServerList>;
+    /** Iterates over every server, page after page. */
+    listAll(params?: Omit<PageParams, "page">, options?: RequestOptions): AsyncGenerator<ServerSummary>;
+    /** One server. IP, port and addon details are hidden for the VIEWER role. */
+    get(serverId: string, options?: RequestOptions): Promise<Server>;
+}
+declare class PlayersResource {
+    private readonly http;
+    private readonly base;
+    constructor(http: Transport, base: string);
+    /** Players of a server, last joined first. `limit`: 1 to 50 (default 15). */
+    list(serverId: string, params?: PageParams & {
+        status?: PlayerStatusFilter;
+    }, options?: RequestOptions): Promise<PlayerList>;
+    /** Iterates over every player of a server. */
+    listAll(serverId: string, params?: {
+        status?: PlayerStatusFilter;
+        limit?: number;
+    }, options?: RequestOptions): AsyncGenerator<Player>;
+    /** One player, by Flitt player id or by external id (SteamID64, license, UUID…). */
+    get(serverId: string, playerId: string, options?: RequestOptions): Promise<Player>;
+}
+declare class FirewallResource {
+    private readonly http;
+    private readonly base;
+    readonly rules: FirewallRulesResource;
+    constructor(http: Transport, base: string);
+    /** Firewall settings and rule counts. */
+    get(serverId: string, options?: RequestOptions): Promise<FirewallSettings>;
+    /** Turns the firewall / VPN blocking on or off, changes the kick message. OWNER or ADMIN. */
+    update(serverId: string, changes: FirewallSettingsUpdate, options?: RequestOptions): Promise<void>;
+    /** Latest blocked connections (1 to 200, default 50). */
+    blocks(serverId: string, params?: {
+        limit?: number;
+    }, options?: RequestOptions): Promise<FirewallBlock[]>;
+}
+declare class FirewallRulesResource {
+    private readonly http;
+    private readonly base;
+    constructor(http: Transport, base: string);
+    list(serverId: string, query?: FirewallRuleQuery, options?: RequestOptions): Promise<FirewallRuleList>;
+    /**
+     * Adds one rule, or up to 100 in one call (e.g. to sync a ban list). OWNER
+     * or ADMIN. Partial success is possible: check `errors` in the result.
+     */
+    create(serverId: string, rules: FirewallRuleInput | FirewallRuleInput[], options?: RequestOptions): Promise<FirewallRuleCreateResult>;
+    /** Removes one rule. */
+    delete(serverId: string, ruleId: string, options?: RequestOptions): Promise<void>;
+    /** Removes rules by ids (up to 500) and / or by action / kind. Returns the number deleted. */
+    deleteMany(serverId: string, filter: FirewallRuleBulkDelete, options?: RequestOptions): Promise<number>;
+}
+declare class DiscordResource {
+    private readonly http;
+    private readonly base;
+    constructor(http: Transport, base: string);
+    /** Discord module state of a server (for API-only setups, without the Flitt bot). */
+    getModule(serverId: string, options?: RequestOptions): Promise<DiscordModule>;
+    /** Turns the addon's Discord module on or off. ADMIN. */
+    setModule(serverId: string, enabled: boolean, options?: RequestOptions): Promise<{
+        serverId: string;
+        moduleEnabled: boolean;
+    }>;
+    /** Code a player types in game to link their Discord account (same flow as the bot's /link). */
+    createLinkCode(discordId: string, options?: RequestOptions): Promise<LinkCode>;
+    /** Links of a Discord user or of a game identity, limited to players seen on your servers. */
+    findLinks(query: {
+        discordId: string;
+    } | {
+        externalId: string;
+    }, options?: RequestOptions): Promise<AccountLink[]>;
+    /** Links a player you verified yourself. The player must have joined the server. ADMIN. */
+    link(serverId: string, input: {
+        discordId: string;
+        externalId: string;
+        name?: string;
+    }, options?: RequestOptions): Promise<AccountLink>;
+    /** Removes the Discord link of a player. ADMIN. */
+    unlink(serverId: string, externalId: string, options?: RequestOptions): Promise<number>;
+}
+declare class CommandsResource {
+    private readonly http;
+    private readonly base;
+    constructor(http: Transport, base: string);
+    /**
+     * Queues a command for the game server's addon. `chat` and `notify` need the
+     * EDITOR role, everything else ADMIN. Set `waitMs` (max 15000) to wait for
+     * the addon's answer. Not retried automatically: a retry could run it twice.
+     */
+    send(serverId: string, input: CommandInput, options?: RequestOptions): Promise<CommandResult>;
+    /** Message in the game chat. */
+    chat(serverId: string, text: string, options?: RequestOptions & {
+        waitMs?: number;
+    }): Promise<CommandResult>;
+    /** Private message to one online player. */
+    notify(serverId: string, externalId: string, message: string, options?: RequestOptions & {
+        waitMs?: number;
+    }): Promise<CommandResult>;
+    kick(serverId: string, externalId: string, reason?: string, options?: RequestOptions & {
+        waitMs?: number;
+    }): Promise<CommandResult>;
+    /** `durationSeconds`: 0 or omitted = permanent. */
+    ban(serverId: string, externalId: string, params?: {
+        reason?: string;
+        durationSeconds?: number;
+    }, options?: RequestOptions & {
+        waitMs?: number;
+    }): Promise<CommandResult>;
+    unban(serverId: string, externalId: string, options?: RequestOptions & {
+        waitMs?: number;
+    }): Promise<CommandResult>;
+    /** Adds (default) or removes an in-game group (ULX, SAM, CAMI, ace groups, LuckPerms or your hooks). */
+    setGroup(serverId: string, externalId: string, group: string, params?: {
+        add?: boolean;
+    }, options?: RequestOptions & {
+        waitMs?: number;
+    }): Promise<CommandResult>;
+    setName(serverId: string, externalId: string, name: string, options?: RequestOptions & {
+        waitMs?: number;
+    }): Promise<CommandResult>;
+    /** Current in-game groups of the online players, as reported by the addon. */
+    groups(serverId: string, options?: RequestOptions): Promise<GroupList>;
+}
+/**
+ * Client of the Flitt Vote API: reward voters from your own scripts when the
+ * Flitt addon is not installed. One token = one server.
+ *
+ * ```ts
+ * import { FlittVotes } from "@flitt/api";
+ * const votes = new FlittVotes({ token: process.env.FLITT_VOTE_TOKEN });
+ * const claim = await votes.claim({ player: "Alex_RP" });
+ * if (claim.status === "CLAIMED_NOW") giveReward("Alex_RP");
+ * ```
+ */
+export declare class FlittVotes {
+    #private;
+    constructor(options?: FlittVotesOptions);
+    /** Quota state from the last response (120 requests / minute per token). */
+    get rateLimit(): RateLimit | null;
+    /** Whether the player has a vote waiting to be claimed (last 24 h). */
+    check(identity: VoteIdentity, options?: RequestOptions): Promise<VoteCheck>;
+    /**
+     * Claims the player's oldest unclaimed vote, exactly once across every
+     * channel (addon, API, NuVotifier). Give the reward only when `status` is
+     * `CLAIMED_NOW`. An idempotency key is generated so automatic retries can
+     * never claim twice; pass your own to make your retries safe too.
+     */
+    claim(identity: VoteIdentity, options?: RequestOptions & {
+        idempotencyKey?: string;
+    }): Promise<VoteClaim>;
+    /** Recent votes, oldest first (up to 30 days back), cursor pagination. */
+    list(params?: VoteListParams, options?: RequestOptions): Promise<VoteList>;
+    /** Iterates over every vote since `since`. */
+    listAll(params?: Omit<VoteListParams, "cursor">, options?: RequestOptions): AsyncGenerator<VoteListItem>;
+    /** Top voters of a month (`current_month`, `last_month`, `all_time` or `YYYY-MM`). */
+    top(params?: {
+        period?: TopVotersPeriod;
+        limit?: number;
+    }, options?: RequestOptions): Promise<TopVoters>;
+    /** Server info: status, votes, ranking, reviews (and stats with `includeStats`). */
+    server(params?: {
+        includeStats?: boolean;
+    }, options?: RequestOptions): Promise<VoteServer>;
+    /** Daily, weekly and monthly votes, page views and join clicks. */
+    stats(options?: RequestOptions): Promise<VoteStats>;
+    /** Published reviews of the server. */
+    reviews(params?: ReviewListParams, options?: RequestOptions): Promise<ReviewList>;
+    toJSON(): {
+        client: string;
+        token: string;
+    };
+    [INSPECT](): string;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}