@rocksky/sdk 0.2.2 → 0.4.0

package/src/jetstream.ts

@@ -0,0 +1,122 @@
+import type { RockskyIndex } from "./dedup.js";
+
+/** The four public Bluesky Jetstream servers. */
+export const DEFAULT_JETSTREAM_SERVERS = [
+  "wss://jetstream1.us-east.bsky.network",
+  "wss://jetstream2.us-east.bsky.network",
+  "wss://jetstream1.us-west.bsky.network",
+  "wss://jetstream2.us-west.bsky.network",
+];
+
+const RECONNECT_SLACK_US = 5_000_000;
+
+export interface JetstreamOptions {
+  /** Servers to connect to at once (defaults to {@link DEFAULT_JETSTREAM_SERVERS}). */
+  servers?: string[];
+  /** Cancels the hydration and closes all connections when aborted. */
+  signal?: AbortSignal;
+}
+
+interface JetEvent {
+  did: string;
+  time_us: number;
+  kind: string;
+  commit?: {
+    operation: string;
+    collection: string;
+    rkey: string;
+    record?: Record<string, unknown>;
+  };
+}
+
+// A shared, mutable watermark — the highest time_us processed across sources.
+interface Watermark {
+  v: number;
+}
+
+/**
+ * Hydrate `idx` from the Bluesky Jetstream firehose for `did`, connecting to
+ * every server at once, filtered to app.rocksky.* + this DID. A shared watermark
+ * de-duplicates the overlap between servers and is the reconnect cursor. Resolves
+ * when opts.signal aborts; each source reconnects with backoff.
+ */
+export async function runJetstream(idx: RockskyIndex, did: string, opts: JetstreamOptions = {}): Promise<void> {
+  const servers = opts.servers ?? DEFAULT_JETSTREAM_SERVERS;
+  const wm: Watermark = { v: await idx.cursor(did) };
+  await Promise.all(servers.map((s) => sourceLoop(s, idx, did, wm, opts.signal)));
+}
+
+async function sourceLoop(server: string, idx: RockskyIndex, did: string, wm: Watermark, signal?: AbortSignal) {
+  while (!signal?.aborted) {
+    const cursor = Math.max(0, wm.v - RECONNECT_SLACK_US);
+    try {
+      await connect(subscribeURL(server, did, cursor), idx, did, wm, signal);
+    } catch {
+      // fall through to backoff
+    }
+    await sleep(2000, signal);
+  }
+}
+
+function connect(url: string, idx: RockskyIndex, did: string, wm: Watermark, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const ws = new WebSocket(url);
+    const onAbort = () => {
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    const done = () => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    };
+
+    ws.onmessage = (ev: MessageEvent) => {
+      let event: JetEvent;
+      try {
+        event = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+      } catch {
+        return;
+      }
+      if (event.kind !== "commit" || event.did !== did || !event.commit) return;
+      // Claim this event for exactly one source (single-threaded: set before await).
+      if (event.time_us <= wm.v) return;
+      wm.v = event.time_us;
+      const c = event.commit;
+      void idx
+        .applyCommit(event.did, c.collection, c.operation, c.rkey, c.record)
+        .then(() => idx.setCursor(did, event.time_us))
+        .catch(() => {});
+    };
+    ws.onclose = done;
+    ws.onerror = () => {
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+      done();
+    };
+  });
+}
+
+function subscribeURL(server: string, did: string, cursorUS: number): string {
+  let u = `${server.replace(/\/+$/, "")}/subscribe?wantedCollections=app.rocksky.*&wantedDids=${encodeURIComponent(did)}`;
+  if (cursorUS > 0) u += `&cursor=${cursorUS}`;
+  return u;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(t);
+      resolve();
+    }, { once: true });
+  });
+}

package/src/http.ts

@@ -1,195 +0,0 @@
-import {
-  RockskyAuthError,
-  RockskyHttpError,
-  RockskyTimeoutError,
-} from "./errors.js";
-import {
-  type AuthProvider,
-  DEFAULT_BASE_URL,
-  type FetchLike,
-  type RequestOptions,
-} from "./types.js";
-
-export type XrpcCallOptions = RequestOptions & {
-  params?: object;
-  body?: unknown;
-  requireAuth?: boolean;
-};
-
-export type HttpClientConfig = {
-  baseUrl: string;
-  auth?: AuthProvider;
-  fetch: FetchLike;
-  headers: Record<string, string>;
-  timeoutMs: number;
-  retries: number;
-  retryDelayMs: number;
-};
-
-export function buildConfig(opts: {
-  baseUrl?: string;
-  auth?: AuthProvider;
-  fetch?: FetchLike;
-  headers?: Record<string, string>;
-  timeoutMs?: number;
-  retries?: number;
-  retryDelayMs?: number;
-  userAgent?: string;
-}): HttpClientConfig {
-  const headers: Record<string, string> = {
-    accept: "application/json",
-    ...(opts.userAgent ? { "user-agent": opts.userAgent } : {}),
-    ...(opts.headers ?? {}),
-  };
-  return {
-    baseUrl: stripTrailingSlash(opts.baseUrl ?? DEFAULT_BASE_URL),
-    auth: opts.auth,
-    fetch: opts.fetch ?? globalThis.fetch.bind(globalThis),
-    headers,
-    timeoutMs: opts.timeoutMs ?? 30_000,
-    retries: opts.retries ?? 0,
-    retryDelayMs: opts.retryDelayMs ?? 300,
-  };
-}
-
-function stripTrailingSlash(url: string): string {
-  return url.endsWith("/") ? url.slice(0, -1) : url;
-}
-
-async function resolveAuth(
-  provider: AuthProvider | undefined | null,
-): Promise<string | undefined> {
-  if (provider == null) return undefined;
-  if (typeof provider === "string") return provider;
-  return await provider();
-}
-
-export function serializeParams(
-  params: object | undefined,
-): string {
-  if (!params) return "";
-  const usp = new URLSearchParams();
-  for (const [k, v] of Object.entries(params as Record<string, unknown>)) {
-    if (v == null) continue;
-    if (Array.isArray(v)) {
-      for (const item of v) {
-        if (item == null) continue;
-        usp.append(k, String(item));
-      }
-    } else if (typeof v === "boolean") {
-      usp.append(k, v ? "true" : "false");
-    } else {
-      usp.append(k, String(v));
-    }
-  }
-  const s = usp.toString();
-  return s ? `?${s}` : "";
-}
-
-export async function xrpcCall<T>(
-  config: HttpClientConfig,
-  nsid: string,
-  method: "GET" | "POST",
-  opts: XrpcCallOptions = {},
-): Promise<T> {
-  const url =
-    `${config.baseUrl}/xrpc/${nsid}` + serializeParams(opts.params);
-
-  const timeoutMs = opts.timeoutMs ?? config.timeoutMs;
-  const retries = opts.retries ?? config.retries;
-
-  const headers: Record<string, string> = {
-    ...config.headers,
-    ...(opts.headers ?? {}),
-  };
-
-  const authProvider = opts.auth === undefined ? config.auth : opts.auth;
-  const token = await resolveAuth(authProvider);
-  if (token) {
-    headers.authorization = `Bearer ${token}`;
-  } else if (opts.requireAuth) {
-    throw new RockskyAuthError(
-      `${nsid} requires authentication — provide an "auth" token`,
-    );
-  }
-
-  const init: RequestInit = {
-    method,
-    headers,
-    signal: opts.signal,
-  };
-
-  if (method === "POST" && opts.body !== undefined) {
-    headers["content-type"] = "application/json";
-    init.body = JSON.stringify(opts.body);
-  }
-
-  let lastErr: unknown;
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    try {
-      return await runOnce<T>(config.fetch, url, init, timeoutMs);
-    } catch (err) {
-      lastErr = err;
-      if (!isRetryable(err) || attempt === retries) throw err;
-      await sleep(config.retryDelayMs * Math.pow(2, attempt));
-    }
-  }
-  throw lastErr;
-}
-
-async function runOnce<T>(
-  fetchImpl: FetchLike,
-  url: string,
-  init: RequestInit,
-  timeoutMs: number,
-): Promise<T> {
-  const controller = new AbortController();
-  const upstream = init.signal;
-  const onAbort = () => controller.abort(upstream?.reason);
-  upstream?.addEventListener("abort", onAbort, { once: true });
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const res = await fetchImpl(url, { ...init, signal: controller.signal });
-    const text = await res.text();
-    const body = parseMaybeJson(text);
-    if (!res.ok) {
-      throw new RockskyHttpError({
-        status: res.status,
-        statusText: res.statusText,
-        url,
-        body,
-      });
-    }
-    return body as T;
-  } catch (err) {
-    if (err instanceof DOMException && err.name === "AbortError") {
-      if (upstream?.aborted) throw err;
-      throw new RockskyTimeoutError(timeoutMs);
-    }
-    throw err;
-  } finally {
-    clearTimeout(timer);
-    upstream?.removeEventListener("abort", onAbort);
-  }
-}
-
-function parseMaybeJson(text: string): unknown {
-  if (!text) return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}
-
-function isRetryable(err: unknown): boolean {
-  if (err instanceof RockskyTimeoutError) return true;
-  if (err instanceof RockskyHttpError) {
-    return err.status >= 500 || err.status === 429;
-  }
-  return false;
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((r) => setTimeout(r, ms));
-}

package/src/namespaces/_helpers.ts

@@ -1,27 +0,0 @@
-import { type HttpClientConfig, xrpcCall } from "../http.js";
-import type { RequestOptions } from "../types.js";
-import type { Endpoints } from "../generated/types.js";
-
-type CallOpts = {
-  params?: object;
-  body?: unknown;
-  requireAuth?: boolean;
-} & RequestOptions;
-
-export interface Call {
-  <K extends keyof Endpoints>(
-    nsid: K,
-    method: "GET" | "POST",
-    opts?: CallOpts,
-  ): Promise<Endpoints[K]>;
-  <T = unknown>(
-    nsid: string,
-    method: "GET" | "POST",
-    opts?: CallOpts,
-  ): Promise<T>;
-}
-
-export function makeCall(config: HttpClientConfig): Call {
-  return ((nsid: string, method: "GET" | "POST", opts?: CallOpts) =>
-    xrpcCall(config, nsid, method, opts ?? {})) as Call;
-}

package/src/namespaces/actor.ts

@@ -1,93 +0,0 @@
-import type {
-  GetActorAlbumsParams,
-  GetActorArtistsParams,
-  GetActorCompatibilityParams,
-  GetActorLovedSongsParams,
-  GetActorNeighboursParams,
-  GetActorPlaylistsParams,
-  GetActorScrobblesParams,
-  GetActorSongsParams,
-  GetProfileParams,
-} from "../generated/types.js";
-import type { RequestOptions } from "../types.js";
-import type { Call } from "./_helpers.js";
-
-export type { GetProfileParams };
-export type ActorPagedParams = GetActorScrobblesParams;
-export type ActorRangeParams = GetActorAlbumsParams;
-
-export class ActorNamespace {
-  constructor(private readonly call: Call) {}
-
-  getProfile(params: GetProfileParams = {}, opts?: RequestOptions) {
-    return this.call("app.rocksky.actor.getProfile", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getActorAlbums(params: GetActorAlbumsParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.actor.getActorAlbums", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getActorArtists(params: GetActorArtistsParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.actor.getActorArtists", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getActorSongs(params: GetActorSongsParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.actor.getActorSongs", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getActorScrobbles(
-    params: GetActorScrobblesParams,
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.actor.getActorScrobbles", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getActorLovedSongs(
-    params: GetActorLovedSongsParams,
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.actor.getActorLovedSongs", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getActorPlaylists(
-    params: GetActorPlaylistsParams,
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.actor.getActorPlaylists", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getActorNeighbours(params: GetActorNeighboursParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.actor.getActorNeighbours", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getActorCompatibility(params: GetActorCompatibilityParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.actor.getActorCompatibility", "GET", {
-      params,
-      ...opts,
-    });
-  }
-}

package/src/namespaces/album.ts

@@ -1,34 +0,0 @@
-import type {
-  GetAlbumParams,
-  GetAlbumsParams,
-  GetAlbumTracksParams,
-} from "../generated/types.js";
-import type { RequestOptions } from "../types.js";
-import type { Call } from "./_helpers.js";
-
-export type { GetAlbumsParams };
-
-export class AlbumNamespace {
-  constructor(private readonly call: Call) {}
-
-  getAlbum(params: GetAlbumParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.album.getAlbum", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getAlbums(params: GetAlbumsParams = {}, opts?: RequestOptions) {
-    return this.call("app.rocksky.album.getAlbums", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getAlbumTracks(params: GetAlbumTracksParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.album.getAlbumTracks", "GET", {
-      params,
-      ...opts,
-    });
-  }
-}

package/src/namespaces/apikey.ts

@@ -1,50 +0,0 @@
-import type {
-  CreateApikeyInput,
-  GetApikeysParams,
-  RemoveApikeyParams,
-  UpdateApikeyInput,
-} from "../generated/types.js";
-import type { RequestOptions } from "../types.js";
-import type { Call } from "./_helpers.js";
-
-export type { CreateApikeyInput, UpdateApikeyInput };
-export type ListApikeysParams = GetApikeysParams;
-
-export class ApikeyNamespace {
-  constructor(private readonly call: Call) {}
-
-  getApikeys(
-    params: ListApikeysParams = {},
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.apikey.getApikeys", "GET", {
-      params,
-      requireAuth: true,
-      ...opts,
-    });
-  }
-
-  createApikey(input: CreateApikeyInput, opts?: RequestOptions) {
-    return this.call("app.rocksky.apikey.createApikey", "POST", {
-      body: input,
-      requireAuth: true,
-      ...opts,
-    });
-  }
-
-  updateApikey(input: UpdateApikeyInput, opts?: RequestOptions) {
-    return this.call("app.rocksky.apikey.updateApikey", "POST", {
-      body: input,
-      requireAuth: true,
-      ...opts,
-    });
-  }
-
-  removeApikey(params: RemoveApikeyParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.apikey.removeApikey", "POST", {
-      params,
-      requireAuth: true,
-      ...opts,
-    });
-  }
-}

package/src/namespaces/artist.ts

@@ -1,68 +0,0 @@
-import type {
-  GetArtistAlbumsParams,
-  GetArtistListenersParams,
-  GetArtistParams,
-  GetArtistRecentListenersParams,
-  GetArtistsParams,
-  GetArtistTracksParams,
-} from "../generated/types.js";
-import type { RequestOptions } from "../types.js";
-import type { Call } from "./_helpers.js";
-
-export type { GetArtistsParams, GetArtistTracksParams };
-export type ArtistListenersParams = GetArtistListenersParams;
-
-export class ArtistNamespace {
-  constructor(private readonly call: Call) {}
-
-  getArtist(params: GetArtistParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.artist.getArtist", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getArtists(params: GetArtistsParams = {}, opts?: RequestOptions) {
-    return this.call("app.rocksky.artist.getArtists", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getArtistAlbums(params: GetArtistAlbumsParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.artist.getArtistAlbums", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getArtistTracks(
-    params: GetArtistTracksParams = {},
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.artist.getArtistTracks", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getArtistListeners(
-    params: GetArtistListenersParams,
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.artist.getArtistListeners", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getArtistRecentListeners(
-    params: GetArtistRecentListenersParams,
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.artist.getArtistRecentListeners", "GET", {
-      params,
-      ...opts,
-    });
-  }
-}

package/src/namespaces/charts.ts

@@ -1,38 +0,0 @@
-import type {
-  GetScrobblesChartParams,
-  GetTopArtistsParams,
-  GetTopTracksParams,
-} from "../generated/types.js";
-import type { RequestOptions } from "../types.js";
-import type { Call } from "./_helpers.js";
-
-export type ScrobblesChartParams = GetScrobblesChartParams;
-export type TopChartParams = GetTopArtistsParams;
-
-export class ChartsNamespace {
-  constructor(private readonly call: Call) {}
-
-  getScrobblesChart(
-    params: ScrobblesChartParams = {},
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.charts.getScrobblesChart", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getTopArtists(params: GetTopArtistsParams = {}, opts?: RequestOptions) {
-    return this.call("app.rocksky.charts.getTopArtists", "GET", {
-      params,
-      ...opts,
-    });
-  }
-
-  getTopTracks(params: GetTopTracksParams = {}, opts?: RequestOptions) {
-    return this.call("app.rocksky.charts.getTopTracks", "GET", {
-      params,
-      ...opts,
-    });
-  }
-}

package/src/namespaces/dropbox.ts

@@ -1,53 +0,0 @@
-import type {
-  DownloadFileParams,
-  GetFilesParams,
-  GetMetadataParams,
-  GetTemporaryLinkParams,
-} from "../generated/types.js";
-import type { RequestOptions } from "../types.js";
-import type { Call } from "./_helpers.js";
-
-export class DropboxNamespace {
-  constructor(private readonly call: Call) {}
-
-  getFiles(
-    params: GetFilesParams = {},
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.dropbox.getFiles", "GET", {
-      params,
-      requireAuth: true,
-      ...opts,
-    });
-  }
-
-  getMetadata(params: GetMetadataParams, opts?: RequestOptions) {
-    return this.call("app.rocksky.dropbox.getMetadata", "GET", {
-      params,
-      requireAuth: true,
-      ...opts,
-    });
-  }
-
-  getTemporaryLink(
-    params: GetTemporaryLinkParams,
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.dropbox.getTemporaryLink", "GET", {
-      params,
-      requireAuth: true,
-      ...opts,
-    });
-  }
-
-  downloadFile(
-    params: DownloadFileParams,
-    opts?: RequestOptions,
-  ) {
-    return this.call("app.rocksky.dropbox.downloadFile", "GET", {
-      params,
-      requireAuth: true,
-      ...opts,
-    });
-  }
-}