@flitt/api 1.2.0 → 1.3.0

package/src/client.ts

@@ -9,6 +9,7 @@ import {
   type FetchLike,
   type RequestOptions,
 } from "./http.js";
+import { FlittEventStream, type EventStreamOptions } from "./events.js";
 import type {
   AccountLink,
   CommandInput,
@@ -164,6 +165,7 @@ export class Flitt {
   readonly votes: VotesResource;
   /** Published reviews. Account key or server token. */
   readonly reviews: ReviewsResource;
+  readonly events: EventsResource;
 
   constructor(options: FlittOptions = {}) {
     const apiKey = (options.apiKey ?? envVar("FLITT_API_KEY") ?? "").trim();
@@ -209,6 +211,7 @@ export class Flitt {
     this.commands = new CommandsResource(http, base);
     this.votes = new VotesResource(votesHttp, base);
     this.reviews = new ReviewsResource(votesHttp, base);
+    this.events = new EventsResource(apiKey || serverToken, normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL), options.dangerouslyAllowBrowser === true);
   }
 
   /** Quota state from the last response (`null` before the first request). */
@@ -225,6 +228,35 @@ export class Flitt {
   }
 }
 
+class EventsResource {
+  #token: string;
+  #baseUrl: string;
+  #allowBrowser: boolean;
+
+  constructor(token: string, baseUrl: string, allowBrowser: boolean) {
+    this.#token = token;
+    this.#baseUrl = baseUrl;
+    this.#allowBrowser = allowBrowser;
+  }
+
+  connect(options: EventStreamOptions = {}): FlittEventStream {
+    if (isBrowserLike() && !this.#allowBrowser) {
+      throw new FlittConfigError(
+        "The Flitt client is running in a browser: your secret key would be exposed to every visitor. " +
+          "Call Flitt from your server (Node.js, Deno, Bun, a Worker…) or set dangerouslyAllowBrowser: true if you understand the risk.",
+      );
+    }
+    return new FlittEventStream(this.#token, this.#baseUrl, options);
+  }
+
+  toJSON() {
+    return { resource: "events", credentials: "[redacted]" };
+  }
+  [INSPECT]() {
+    return "EventsResource { credentials: [redacted] }";
+  }
+}
+
 class ServersResource {
   constructor(private readonly http: Transport, private readonly base: string) {}
 

package/src/events.ts

@@ -0,0 +1,354 @@
+import { apiErrorFor, FlittConfigError, FlittConnectionError, FlittError } from "./errors.js";
+import type { WebhookEvent, WebhookEventType } from "./types.js";
+
+export type WebSocketLike = {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: string, listener: (event: any) => void): void;
+};
+
+export type WebSocketConstructor = new (url: string) => WebSocketLike;
+
+export type FlittEvent<T = Record<string, unknown> | null> = WebhookEvent<T> & {
+  id: string;
+  replay: boolean;
+};
+
+export type EventStreamOptions = {
+  servers?: string[];
+  events?: WebhookEventType[];
+  resume?: boolean;
+  lastEventIds?: Record<string, string>;
+  WebSocket?: WebSocketConstructor;
+  signal?: AbortSignal;
+  maxReconnectDelayMs?: number;
+  bufferSize?: number;
+};
+
+export type EventStreamReady = { servers: string[]; events: WebhookEventType[] };
+export type EventStreamReconnect = { attempt: number; delayMs: number; code: number };
+export type EventStreamGap = { serverId: string };
+export type EventStreamClose = { code: number; reason: string };
+
+type Listener = (payload: any) => void;
+
+const PATH = "/v1/public-api/events";
+const PING_EVERY_MS = 30_000;
+const IDLE_TIMEOUT_MS = 75_000;
+const OPEN_TIMEOUT_MS = 20_000;
+const FATAL: Record<number, { status: number; code: string; message: string }> = {
+  4001: { status: 401, code: "UNAUTHORIZED", message: "Invalid, revoked or expired credentials" },
+  4002: { status: 400, code: "BAD_REQUEST", message: "Invalid subscription (servers, events or resume)" },
+  4003: { status: 403, code: "FORBIDDEN", message: "Your plan or your account does not allow real-time events" },
+  4004: { status: 404, code: "NOT_FOUND", message: "No accessible server or event for this subscription" },
+};
+const STREAM_ID = /^\d{1,15}-\d{1,10}$/;
+
+function compareIds(a: string, b: string): number {
+  const [am, as] = a.split("-");
+  const [bm, bs] = b.split("-");
+  const dm = Number(am) - Number(bm);
+  return dm !== 0 ? dm : Number(as) - Number(bs);
+}
+
+function safeClose(ws: WebSocketLike, code: number, reason: string) {
+  try {
+    ws.close(code, reason);
+  } catch {
+    return;
+  }
+}
+
+export function eventsUrl(baseUrl: string): string {
+  return baseUrl.replace(/^http/, "ws") + PATH;
+}
+
+export function resolveWebSocket(custom?: WebSocketConstructor): WebSocketConstructor {
+  if (custom) return custom;
+  const ws = (globalThis as { WebSocket?: WebSocketConstructor }).WebSocket;
+  if (typeof ws !== "function") {
+    throw new FlittConfigError("No global WebSocket in this runtime: use Node.js 22+, or pass { WebSocket } from the \"ws\" package (npm i ws).");
+  }
+  return ws;
+}
+
+export class FlittEventStream implements AsyncIterable<FlittEvent> {
+  #token: string;
+  #url: string;
+  #WebSocket: WebSocketConstructor;
+  #servers: string[] | undefined;
+  #events: WebhookEventType[] | undefined;
+  #resume: boolean;
+  #maxDelay: number;
+  #bufferSize: number;
+  #lastIds = new Map<string, string>();
+  #listeners = new Map<string, Set<Listener>>();
+  #iterators = new Set<{ queue: FlittEvent[]; wake: (() => void) | null }>();
+  #ws: WebSocketLike | null = null;
+  #ready = false;
+  #closed = false;
+  #fatal: FlittError | null = null;
+  #attempt = 0;
+  #lastRx = 0;
+  #openedAt = 0;
+  #retry: ReturnType<typeof setTimeout> | null = null;
+  #timer: ReturnType<typeof setInterval> | null = null;
+  #onAbort: (() => void) | null = null;
+  #signal: AbortSignal | undefined;
+
+  constructor(token: string, baseUrl: string, options: EventStreamOptions = {}) {
+    this.#token = token;
+    this.#url = eventsUrl(baseUrl);
+    this.#WebSocket = resolveWebSocket(options.WebSocket);
+    this.#servers = options.servers?.length ? [...new Set(options.servers.map((s) => String(s).trim().toLowerCase()))] : undefined;
+    this.#events = options.events?.length ? [...new Set(options.events)] : undefined;
+    this.#resume = options.resume !== false;
+    this.#maxDelay = Math.max(1000, Math.min(300_000, options.maxReconnectDelayMs ?? 30_000));
+    this.#bufferSize = Math.max(1, Math.min(100_000, options.bufferSize ?? 1000));
+    for (const [serverId, id] of Object.entries(options.lastEventIds ?? {})) {
+      if (STREAM_ID.test(id)) this.#lastIds.set(serverId, id);
+    }
+    if (this.#servers && this.#servers.length > 200) throw new FlittConfigError("servers: 200 at most per stream.");
+    this.#signal = options.signal;
+    if (this.#signal?.aborted) {
+      this.#closed = true;
+      return;
+    }
+    if (this.#signal) {
+      this.#onAbort = () => this.close();
+      this.#signal.addEventListener("abort", this.#onAbort, { once: true });
+    }
+    this.#timer = setInterval(() => this.#watchdog(), 5_000);
+    this.#connect();
+  }
+
+  get connected(): boolean {
+    return this.#ready;
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  get lastEventIds(): Record<string, string> {
+    return Object.fromEntries(this.#lastIds);
+  }
+
+  on(type: "event", listener: (event: FlittEvent) => void): this;
+  on(type: WebhookEventType, listener: (event: FlittEvent) => void): this;
+  on(type: "ready", listener: (info: EventStreamReady) => void): this;
+  on(type: "reconnecting", listener: (info: EventStreamReconnect) => void): this;
+  on(type: "gap", listener: (info: EventStreamGap) => void): this;
+  on(type: "error", listener: (error: FlittError) => void): this;
+  on(type: "close", listener: (info: EventStreamClose) => void): this;
+  on(type: string, listener: Listener): this {
+    let set = this.#listeners.get(type);
+    if (!set) {
+      set = new Set();
+      this.#listeners.set(type, set);
+    }
+    set.add(listener);
+    return this;
+  }
+
+  off(type: string, listener: Listener): this {
+    this.#listeners.get(type)?.delete(listener);
+    return this;
+  }
+
+  once(type: string, listener: Listener): this {
+    const wrapped: Listener = (payload) => {
+      this.off(type, wrapped);
+      listener(payload);
+    };
+    return this.on(type as "event", wrapped);
+  }
+
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#shutdown(1000, "closed by client");
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<FlittEvent> {
+    const it = { queue: [] as FlittEvent[], wake: null as (() => void) | null };
+    this.#iterators.add(it);
+    try {
+      while (true) {
+        if (it.queue.length > 0) {
+          yield it.queue.shift() as FlittEvent;
+          continue;
+        }
+        if (this.#fatal) throw this.#fatal;
+        if (this.#closed) return;
+        await new Promise<void>((resolve) => (it.wake = resolve));
+        it.wake = null;
+      }
+    } finally {
+      this.#iterators.delete(it);
+    }
+  }
+
+  toJSON() {
+    return { stream: "FlittEventStream", connected: this.#ready, credentials: "[redacted]" };
+  }
+
+  #emit(type: string, payload: unknown) {
+    const set = this.#listeners.get(type);
+    if (!set) return;
+    for (const fn of [...set]) {
+      try {
+        fn(payload);
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  #wakeIterators() {
+    for (const it of this.#iterators) it.wake?.();
+  }
+
+  #connect() {
+    if (this.#closed) return;
+    this.#retry = null;
+    this.#ready = false;
+    this.#openedAt = Date.now();
+    let ws: WebSocketLike;
+    try {
+      ws = new this.#WebSocket(this.#url);
+    } catch (err) {
+      this.#scheduleReconnect(1006, err);
+      return;
+    }
+    this.#ws = ws;
+    ws.addEventListener("open", () => {
+      if (this.#ws !== ws) return;
+      this.#lastRx = Date.now();
+      const hello: Record<string, unknown> = { op: "hello", token: this.#token };
+      if (this.#servers) hello.servers = this.#servers;
+      if (this.#events) hello.events = this.#events;
+      if (this.#resume && this.#lastIds.size > 0) hello.resume = Object.fromEntries(this.#lastIds);
+      try {
+        ws.send(JSON.stringify(hello));
+      } catch {
+        return;
+      }
+    });
+    ws.addEventListener("message", (ev: { data: unknown }) => {
+      if (this.#ws !== ws) return;
+      this.#lastRx = Date.now();
+      if (typeof ev.data === "string") this.#onFrame(ev.data);
+    });
+    ws.addEventListener("close", (ev: { code?: number; reason?: string }) => {
+      if (this.#ws !== ws) return;
+      this.#onClose(Number(ev?.code ?? 1006), String(ev?.reason ?? ""));
+    });
+    ws.addEventListener("error", () => undefined);
+  }
+
+  #onFrame(text: string) {
+    let msg: any;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (!msg || typeof msg !== "object") return;
+    if (msg.op === "event") {
+      const serverId = String(msg.server?.id ?? "");
+      const id = String(msg.id ?? "");
+      if (!serverId || !STREAM_ID.test(id)) return;
+      const last = this.#lastIds.get(serverId);
+      if (last && compareIds(id, last) <= 0) return;
+      this.#lastIds.set(serverId, id);
+      const event: FlittEvent = {
+        id,
+        replay: msg.replay === true,
+        event: msg.event,
+        timestamp: msg.timestamp,
+        server: { id: serverId, name: msg.server?.name ?? null },
+        data: msg.data ?? null,
+      };
+      for (const it of this.#iterators) {
+        it.queue.push(event);
+        if (it.queue.length > this.#bufferSize) it.queue.shift();
+      }
+      this.#wakeIterators();
+      this.#emit("event", event);
+      this.#emit(event.event, event);
+    } else if (msg.op === "ready") {
+      this.#ready = true;
+      this.#attempt = 0;
+      this.#emit("ready", { servers: Array.isArray(msg.servers) ? msg.servers : [], events: Array.isArray(msg.events) ? msg.events : [] });
+    } else if (msg.op === "gap" && typeof msg.serverId === "string") {
+      this.#emit("gap", { serverId: msg.serverId });
+    }
+  }
+
+  #onClose(code: number, reason: string) {
+    this.#ws = null;
+    this.#ready = false;
+    if (this.#closed) return;
+    const fatal = FATAL[code];
+    if (fatal) {
+      this.#fatal = apiErrorFor({ ...fatal, method: "GET", path: PATH });
+      this.#emit("error", this.#fatal);
+      this.#closed = true;
+      this.#shutdown(code, reason || fatal.message);
+      return;
+    }
+    this.#scheduleReconnect(code);
+  }
+
+  #scheduleReconnect(code: number, cause?: unknown) {
+    if (this.#closed || this.#retry) return;
+    this.#attempt += 1;
+    const base = code === 1012 || code === 1001 ? 500 : code === 4029 ? 30_000 : Math.min(this.#maxDelay, 1000 * 2 ** Math.min(this.#attempt - 1, 8));
+    const delayMs = Math.min(this.#maxDelay, Math.round(base * (1 + Math.random() * 0.3)));
+    if (cause !== undefined) this.#emit("error", new FlittConnectionError("Event stream connection failed", { cause }));
+    this.#emit("reconnecting", { attempt: this.#attempt, delayMs, code });
+    this.#retry = setTimeout(() => this.#connect(), delayMs);
+  }
+
+  #watchdog() {
+    const ws = this.#ws;
+    if (!ws || this.#closed) return;
+    const now = Date.now();
+    if (!this.#ready) {
+      if (now - this.#openedAt > OPEN_TIMEOUT_MS) this.#drop(ws);
+      return;
+    }
+    if (now - this.#lastRx > IDLE_TIMEOUT_MS) return this.#drop(ws);
+    if (now - this.#lastRx > PING_EVERY_MS) {
+      try {
+        ws.send('{"op":"ping"}');
+      } catch {
+        this.#drop(ws);
+      }
+    }
+  }
+
+  #drop(ws: WebSocketLike) {
+    this.#ws = null;
+    safeClose(ws, 4000, "timeout");
+    this.#ready = false;
+    this.#scheduleReconnect(1006);
+  }
+
+  #shutdown(code: number, reason: string) {
+    if (this.#retry) clearTimeout(this.#retry);
+    this.#retry = null;
+    if (this.#timer) clearInterval(this.#timer);
+    this.#timer = null;
+    if (this.#onAbort) this.#signal?.removeEventListener("abort", this.#onAbort);
+    this.#onAbort = null;
+    const ws = this.#ws;
+    this.#ws = null;
+    this.#ready = false;
+    if (ws) safeClose(ws, 1000, "closed by client");
+    this.#wakeIterators();
+    this.#emit("close", { code, reason });
+  }
+}

package/src/index.ts

@@ -5,6 +5,17 @@
 export { Flitt, FlittVotes, DEFAULT_BASE_URL } from "./client.js";
 export type { ClientOptions, FlittOptions, FlittVotesOptions } from "./client.js";
 export type { FetchLike, RequestOptions } from "./http.js";
+export { FlittEventStream } from "./events.js";
+export type {
+  FlittEvent,
+  EventStreamOptions,
+  EventStreamReady,
+  EventStreamReconnect,
+  EventStreamGap,
+  EventStreamClose,
+  WebSocketConstructor,
+  WebSocketLike,
+} from "./events.js";
 export { verifyWebhook, FlittWebhookError } from "./webhooks.js";
 export type { VerifyWebhookOptions, HeaderSource } from "./webhooks.js";
 export {

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.2.0";
+export const VERSION = "1.3.0";