@flitt/api 1.0.0 → 1.2.0

package/src/client.ts

@@ -30,6 +30,7 @@ import type {
   PlayerList,
   PlayerStatusFilter,
   RateLimit,
+  Review,
   ReviewList,
   ReviewListParams,
   Server,
@@ -46,6 +47,7 @@ import type {
   VoteListParams,
   VoteServer,
   VoteStats,
+  VoteSummary,
 } from "./types.js";
 
 export const DEFAULT_BASE_URL = "https://api.flitt.me";
@@ -74,12 +76,22 @@ export type ClientOptions = {
 };
 
 export type FlittOptions = ClientOptions & {
-  /** Public API key (`flt_…`, Profile → API). Default: `process.env.FLITT_API_KEY`. */
+  /**
+   * Account API key (`flt_…`, Profile → API): every endpoint, on every server
+   * you own or are a member of. Default: `process.env.FLITT_API_KEY`.
+   */
   apiKey?: string;
+  /**
+   * Server token (`flv_…`, Dashboard → your server → Votes → API): votes and
+   * reviews of that one server only. The credential to put on a game server.
+   * Default: `process.env.FLITT_SERVER_TOKEN` (or `FLITT_VOTE_TOKEN`).
+   */
+  serverToken?: string;
 };
 
+/** @deprecated since 1.1: use `new Flitt({ serverToken })` and `flitt.votes`. */
 export type FlittVotesOptions = ClientOptions & {
-  /** Vote API token of one server (`flv_…`, Dashboard → server → Votes). Default: `process.env.FLITT_VOTE_TOKEN`. */
+  /** Server token (`flv_…`). Default: `process.env.FLITT_VOTE_TOKEN`. */
   token?: string;
 };
 
@@ -137,7 +149,7 @@ function positiveInt(value: number | undefined, name: string, max: number): numb
  * ```
  */
 export class Flitt {
-  readonly #http: Transport;
+  #lastRateLimit: RateLimit | null = null;
 
   /** Your account's monthly quota. */
   readonly usage: {
@@ -148,19 +160,45 @@ export class Flitt {
   readonly firewall: FirewallResource;
   readonly discord: DiscordResource;
   readonly commands: CommandsResource;
+  /** Votes: check, claim (idempotent), list, top voters, summary, stats. Account key or server token. */
+  readonly votes: VotesResource;
+  /** Published reviews. Account key or server token. */
+  readonly reviews: ReviewsResource;
 
   constructor(options: FlittOptions = {}) {
     const apiKey = (options.apiKey ?? envVar("FLITT_API_KEY") ?? "").trim();
-    if (!apiKey) throw new FlittConfigError("Missing API key: pass { apiKey } or set FLITT_API_KEY.");
-    if (!API_KEY_FORMAT.test(apiKey)) {
+    const serverToken = (options.serverToken ?? envVar("FLITT_SERVER_TOKEN") ?? envVar("FLITT_VOTE_TOKEN") ?? "").trim();
+    if (!apiKey && !serverToken) {
+      throw new FlittConfigError(
+        "Missing credentials: pass { apiKey } (flt_…) or { serverToken } (flv_…), or set FLITT_API_KEY / FLITT_SERVER_TOKEN.",
+      );
+    }
+    if (apiKey && !API_KEY_FORMAT.test(apiKey)) {
       throw new FlittConfigError(
         apiKey.startsWith("flv_")
-          ? "This is a Vote API token (flv_…): use `new FlittVotes({ token })` instead."
+          ? "This is a server token (flv_…): pass it as { serverToken }."
           : "Invalid API key format: Flitt API keys start with flt_ (Profile → API).",
       );
     }
-    this.#http = buildTransport(apiKey, options, false);
-    const http = this.#http;
+    if (serverToken && !VOTE_TOKEN_FORMAT.test(serverToken)) {
+      throw new FlittConfigError(
+        serverToken.startsWith("flt_")
+          ? "This is an account API key (flt_…): pass it as { apiKey }."
+          : "Invalid server token format: server tokens start with flv_ (Dashboard → your server → Votes → API).",
+      );
+    }
+    const tracked: ClientOptions = {
+      ...options,
+      onRateLimit: (rl: RateLimit) => {
+        this.#lastRateLimit = rl;
+        options.onRateLimit?.(rl);
+      },
+    };
+    const accountHttp = apiKey ? buildTransport(apiKey, tracked, false) : null;
+    const tokenHttp = serverToken ? buildTransport(serverToken, tracked, false) : null;
+    // Account endpoints need the account key; votes and reviews take either (account key first).
+    const http = accountHttp ?? (missingApiKey as unknown as Transport);
+    const votesHttp = (accountHttp ?? tokenHttp) as Transport;
     const base = "/v1/public-api";
 
     this.usage = { get: async (o) => http.request<Usage>("GET", `${base}/usage`, o) };
@@ -169,19 +207,21 @@ export class Flitt {
     this.firewall = new FirewallResource(http, base);
     this.discord = new DiscordResource(http, base);
     this.commands = new CommandsResource(http, base);
+    this.votes = new VotesResource(votesHttp, base);
+    this.reviews = new ReviewsResource(votesHttp, base);
   }
 
   /** Quota state from the last response (`null` before the first request). */
   get rateLimit(): RateLimit | null {
-    return this.#http.lastRateLimit;
+    return this.#lastRateLimit;
   }
 
-  /** Never prints the key. */
+  /** Never prints the credentials. */
   toJSON() {
-    return { client: "Flitt", apiKey: "[redacted]" };
+    return { client: "Flitt", credentials: "[redacted]" };
   }
   [INSPECT]() {
-    return "Flitt { apiKey: [redacted] }";
+    return "Flitt { credentials: [redacted] }";
   }
 }
 
@@ -442,6 +482,105 @@ class CommandsResource {
   }
 }
 
+/** Stand-in transport when only a server token was given: account endpoints explain what is missing. */
+const missingApiKey = {
+  lastRateLimit: null,
+  async request(): Promise<never> {
+    throw new FlittConfigError(
+      "This endpoint needs an account API key (flt_…, Profile → API). A server token (flv_…) only opens votes and reviews.",
+    );
+  },
+};
+
+class VotesResource {
+  constructor(private readonly http: Transport, private readonly base: string) {}
+
+  private path(serverId: string, rest = ""): string {
+    return `${this.base}/servers/${segment(serverId, "serverId")}/votes${rest}`;
+  }
+
+  /** Whether the player has a vote waiting to be claimed (last 24 h). */
+  async check(serverId: string, identity: VoteIdentity, options?: RequestOptions): Promise<VoteCheck> {
+    return this.http.request<VoteCheck>("GET", this.path(serverId, "/check"), { ...options, query: identityParams(identity) });
+  }
+
+  /**
+   * 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. With an
+   * account key, your role needs the "manage votes" permission.
+   */
+  async claim(serverId: string, identity: VoteIdentity, options?: RequestOptions & { idempotencyKey?: string }): Promise<VoteClaim> {
+    const idempotencyKey = options?.idempotencyKey ?? randomKey();
+    if (idempotencyKey.length > 128) throw new FlittConfigError("idempotencyKey: 128 characters max.");
+    return this.http.request<VoteClaim>("POST", this.path(serverId, "/claim"), { ...options, body: identityParams(identity), idempotencyKey });
+  }
+
+  /** Recent votes, oldest first (up to 30 days back), cursor pagination. */
+  async list(serverId: string, params: VoteListParams = {}, options?: RequestOptions): Promise<VoteList> {
+    return this.http.request<VoteList>("GET", this.path(serverId), {
+      ...options,
+      query: { since: params.since, limit: positiveInt(params.limit, "limit", 100), cursor: params.cursor },
+    });
+  }
+
+  /** Iterates over every vote since `since`. */
+  async *listAll(serverId: string, params: Omit<VoteListParams, "cursor"> = {}, options?: RequestOptions): AsyncGenerator<VoteListItem> {
+    let cursor: string | undefined;
+    for (;;) {
+      const res = await this.list(serverId, { ...params, cursor }, options);
+      yield* res.votes;
+      if (!res.nextCursor) return;
+      cursor = res.nextCursor;
+    }
+  }
+
+  /** Top voters of a month (`current_month`, `last_month`, `all_time` or `YYYY-MM`). */
+  async top(serverId: string, params: { period?: TopVotersPeriod; limit?: number } = {}, options?: RequestOptions): Promise<TopVoters> {
+    return this.http.request<TopVoters>("GET", this.path(serverId, "/top"), {
+      ...options,
+      query: { period: params.period, limit: positiveInt(params.limit, "limit", 50) },
+    });
+  }
+
+  /** Vote counters, ranking, status and rating (and the history with `includeStats`). */
+  async summary(serverId: string, params: { includeStats?: boolean } = {}, options?: RequestOptions): Promise<VoteSummary> {
+    return this.http.request<VoteSummary>("GET", this.path(serverId, "/summary"), {
+      ...options,
+      query: { include: params.includeStats ? "stats" : undefined },
+    });
+  }
+
+  /** Daily, weekly and monthly votes, page views and join clicks. */
+  async stats(serverId: string, options?: RequestOptions): Promise<VoteStats> {
+    return this.http.request<VoteStats>("GET", this.path(serverId, "/stats"), options);
+  }
+}
+
+class ReviewsResource {
+  constructor(private readonly http: Transport, private readonly base: string) {}
+
+  /** Published reviews of a server. */
+  async list(serverId: string, params: ReviewListParams = {}, options?: RequestOptions): Promise<ReviewList> {
+    return this.http.request<ReviewList>("GET", `${this.base}/servers/${segment(serverId, "serverId")}/reviews`, {
+      ...options,
+      query: { limit: positiveInt(params.limit, "limit", 50), cursor: params.cursor, sort: params.sort },
+    });
+  }
+
+  /** Iterates over every published review. */
+  async *listAll(serverId: string, params: Omit<ReviewListParams, "cursor"> = {}, options?: RequestOptions): AsyncGenerator<Review> {
+    let cursor: string | undefined;
+    for (;;) {
+      const res = await this.list(serverId, { ...params, cursor }, options);
+      yield* res.reviews;
+      if (!res.nextCursor) return;
+      cursor = res.nextCursor;
+    }
+  }
+}
+
 function snowflake(value: string): string {
   const v = String(value ?? "").trim();
   if (!/^\d{15,22}$/.test(v)) throw new FlittConfigError("discordId must be a Discord user id (15 to 22 digits).");
@@ -474,6 +613,10 @@ function identityParams(identity: VoteIdentity): Record<string, string> {
 }
 
 /**
+ * @deprecated since 1.1 — votes are part of the Public API: use
+ * `new Flitt({ serverToken })` and `flitt.votes.claim(serverId, identity)`.
+ * Kept so 1.0 code keeps working (it calls the legacy /v1/vote-api routes).
+ *
  * Client of the Flitt Vote API: reward voters from your own scripts when the
  * Flitt addon is not installed. One token = one server.
  *
@@ -493,7 +636,7 @@ export class FlittVotes {
     if (!VOTE_TOKEN_FORMAT.test(token)) {
       throw new FlittConfigError(
         token.startsWith("flt_")
-          ? "This is a Public API key (flt_…): use `new Flitt({ apiKey })` instead."
+          ? "This is an account API key (flt_…): use `new Flitt({ apiKey })` instead."
           : "Invalid vote token format: vote tokens start with flv_ (Dashboard → your server → Votes → Vote API).",
       );
     }

package/src/http.ts

@@ -191,12 +191,28 @@ function describeError(status: number, statusText: string, body: unknown, text:
 }
 
 export class Transport {
-  private readonly opts: TransportOptions;
+  // Real private fields (not TypeScript `private`): the token and the options
+  // holding it cannot be reached by console.log, util.inspect or JSON.stringify.
+  readonly #opts: Omit<TransportOptions, "token">;
+  readonly #token: string;
   /** Quota state from the last response carrying X-RateLimit-* headers. */
   lastRateLimit: RateLimit | null = null;
 
   constructor(opts: TransportOptions) {
-    this.opts = opts;
+    const { token, ...rest } = opts;
+    this.#token = token;
+    this.#opts = rest;
+  }
+
+  toJSON() {
+    return { baseUrl: this.#opts.baseUrl, token: "[redacted]" };
+  }
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    return `Transport { baseUrl: ${this.#opts.baseUrl}, token: [redacted] }`;
+  }
+
+  private get opts() {
+    return this.#opts;
   }
 
   async request<T>(method: string, path: string, call: Call = {}): Promise<T> {
@@ -208,7 +224,7 @@ export class Transport {
     const headers: Record<string, string> = {
       Accept: "application/json",
       ...this.opts.headers,
-      Authorization: `Bearer ${this.opts.token}`,
+      Authorization: `Bearer ${this.#token}`,
     };
     // Browsers forbid setting User-Agent; elsewhere it identifies the SDK in our logs.
     if (!isBrowserLike()) headers["User-Agent"] = this.opts.userAgent ?? `flitt-api-js/${VERSION}`;

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @flitt/api — official client of the Flitt Public API and Vote API.
+ * @flitt/api — official client of the Flitt Public API (votes included).
  * https://flitt.me/docs/public-api
  */
 export { Flitt, FlittVotes, DEFAULT_BASE_URL } from "./client.js";

package/src/types.ts

@@ -1,6 +1,6 @@
 /**
- * Response types of the Flitt Public API v1 (`/v1/public-api`) and of the
- * Vote API (`/v1/vote-api`). Dates are ISO 8601 strings, as sent by the API.
+ * Response types of the Flitt Public API v1 (`/v1/public-api`), votes and
+ * reviews included. Dates are ISO 8601 strings, as sent by the API.
  */
 
 export type Game = "GMOD" | "FIVEM" | "MC";
@@ -48,6 +48,20 @@ export type Usage = {
   resetAt: string;
 };
 
+/**
+ * Extended status set by the owner: maintenance, development or temporary
+ * closure. While set, the uptime is paused (checks count neither as online nor
+ * offline) and up / down alerts are muted.
+ */
+export type ServerHold = {
+  kind: "MAINTENANCE" | "DEVELOPMENT" | "CLOSED";
+  /** Owner's note for the players, if any. */
+  message: string | null;
+  since: string;
+  /** Planned end (the status ends by itself then), `null` when not announced. */
+  until: string | null;
+};
+
 export type ServerSummary = {
   id: string;
   game: Game;
@@ -61,6 +75,8 @@ export type ServerSummary = {
   rating: number;
   reviewsCount: number;
   verifiedBadge: boolean;
+  /** Maintenance / development / closure, `null` when the server runs normally. */
+  hold: ServerHold | null;
   createdAt: string | null;
 };
 
@@ -92,6 +108,8 @@ export type Server = {
   rating: number;
   reviewsCount: number;
   status: OnlineStatus;
+  /** Maintenance / development / closure, `null` when the server runs normally. */
+  hold: ServerHold | null;
   accessRole: AccessRole;
 };
 
@@ -264,7 +282,9 @@ export type WebhookEventType =
   | "review_created"
   | "vote_created"
   | "affluence_low"
-  | "affluence_high";
+  | "affluence_high"
+  | "server_hold_started"
+  | "server_hold_ended";
 
 /** Body of a generic (HTTP) webhook. */
 export type WebhookEvent<T = Record<string, unknown> | null> = {
@@ -275,7 +295,7 @@ export type WebhookEvent<T = Record<string, unknown> | null> = {
 };
 
 // ---------------------------------------------------------------------------
-// Vote API
+// Votes and reviews (part of the Public API)
 // ---------------------------------------------------------------------------
 
 type IdentityFields = {
@@ -355,7 +375,8 @@ export type VoteStats = {
   monthly: Array<{ month: string; votes: number; views: number; joinClicks: number; rank: number | null }>;
 };
 
-export type VoteServer = {
+/** Vote counters, ranking, status and rating of a server (`flitt.votes.summary`). */
+export type VoteSummary = {
   id: string;
   name: string | null;
   game: Game;
@@ -370,6 +391,9 @@ export type VoteServer = {
   stats?: VoteStats;
 };
 
+/** @deprecated since 1.1: renamed VoteSummary. */
+export type VoteServer = VoteSummary;
+
 export type Review = {
   id: string;
   rating: number;

package/src/version.ts

@@ -1,2 +1,2 @@
 /** Package version, kept in sync with package.json by scripts/sync-version.mjs. */
-export const VERSION = "1.0.0";
+export const VERSION = "1.2.0";