@rocksky/sdk 0.1.0

package/src/http.ts

@@ -0,0 +1,195 @@
+import {
+  RockskyAuthError,
+  RockskyHttpError,
+  RockskyTimeoutError,
+} from "./errors";
+import {
+  type AuthProvider,
+  DEFAULT_BASE_URL,
+  type FetchLike,
+  type RequestOptions,
+} from "./types";
+
+export type XrpcCallOptions = RequestOptions & {
+  params?: Record<string, unknown>;
+  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: Record<string, unknown> | undefined,
+): string {
+  if (!params) return "";
+  const usp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    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/index.ts

@@ -0,0 +1,85 @@
+export {
+  RockskyClient,
+  RockskyClientBuilder,
+  createClient,
+} from "./client";
+export {
+  RockskyError,
+  RockskyHttpError,
+  RockskyTimeoutError,
+  RockskyAuthError,
+} from "./errors";
+export {
+  pipe,
+  map,
+  tap,
+  withRetry,
+  withTimeout,
+  withFallback,
+  catchError,
+  type Op,
+} from "./pipe";
+export {
+  DEFAULT_BASE_URL,
+  type AuthProvider,
+  type ClientOptions,
+  type FetchLike,
+  type Json,
+  type Pagination,
+  type RequestOptions,
+} from "./types";
+export {
+  paginate,
+  type PageOpts,
+  type PageResult,
+  type PaginateArgs,
+} from "./paginate";
+export {
+  RealtimeClient,
+  RealtimeClientBuilder,
+  createRealtimeClient,
+  type RealtimeOptions,
+  type RealtimeEvent,
+  type RealtimeEventMap,
+  type ReconnectOptions,
+  type WebSocketCtor,
+  type WebSocketLike,
+} from "./realtime";
+
+export type {
+  GetProfileParams,
+  ActorPagedParams,
+  ActorRangeParams,
+} from "./namespaces/actor";
+export type {
+  CreateScrobbleInput,
+  GetScrobblesParams,
+} from "./namespaces/scrobble";
+export type {
+  GetSongParams,
+  GetSongsParams,
+  MatchSongParams,
+  CreateSongInput,
+} from "./namespaces/song";
+export type { GetAlbumsParams } from "./namespaces/album";
+export type {
+  GetArtistsParams,
+  ArtistListenersParams,
+  GetArtistTracksParams,
+} from "./namespaces/artist";
+export type {
+  ListApikeysParams,
+  CreateApikeyInput,
+  UpdateApikeyInput,
+} from "./namespaces/apikey";
+export type {
+  ScrobblesChartParams,
+  TopChartParams,
+} from "./namespaces/charts";
+export type {
+  FollowListParams,
+  KnownFollowersParams,
+} from "./namespaces/graph";
+export type { RecommendParams } from "./namespaces/feed";
+export type { LikeInput } from "./namespaces/like";
+export type { PutMirrorSourceInput } from "./namespaces/mirror";

package/src/namespaces/_helpers.ts

@@ -0,0 +1,17 @@
+import { type HttpClientConfig, xrpcCall } from "../http";
+import type { RequestOptions } from "../types";
+
+export type Call = <T>(
+  nsid: string,
+  method: "GET" | "POST",
+  opts?: {
+    params?: Record<string, unknown>;
+    body?: unknown;
+    requireAuth?: boolean;
+  } & RequestOptions,
+) => Promise<T>;
+
+export function makeCall(config: HttpClientConfig): Call {
+  return (nsid, method, opts) =>
+    xrpcCall(config, nsid, method, opts ?? {});
+}

package/src/namespaces/actor.ts

@@ -0,0 +1,89 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export type GetProfileParams = { did?: string };
+export type DidParam = { did: string };
+export type ActorPagedParams = DidParam & {
+  limit?: number;
+  offset?: number;
+};
+export type ActorRangeParams = ActorPagedParams & {
+  startDate?: string;
+  endDate?: string;
+};
+
+export class ActorNamespace {
+  constructor(private readonly call: Call) {}
+
+  getProfile<T = unknown>(params: GetProfileParams = {}, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.actor.getProfile", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getActorAlbums<T = unknown>(params: ActorRangeParams, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.actor.getActorAlbums", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getActorArtists<T = unknown>(params: ActorRangeParams, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.actor.getActorArtists", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getActorSongs<T = unknown>(params: ActorRangeParams, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.actor.getActorSongs", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getActorScrobbles<T = unknown>(
+    params: ActorPagedParams,
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.actor.getActorScrobbles", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getActorLovedSongs<T = unknown>(
+    params: ActorPagedParams,
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.actor.getActorLovedSongs", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getActorPlaylists<T = unknown>(
+    params: ActorPagedParams,
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.actor.getActorPlaylists", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getActorNeighbours<T = unknown>(params: DidParam, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.actor.getActorNeighbours", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getActorCompatibility<T = unknown>(params: DidParam, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.actor.getActorCompatibility", "GET", {
+      params,
+      ...opts,
+    });
+  }
+}

package/src/namespaces/album.ts

@@ -0,0 +1,34 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export type UriParam = { uri: string };
+export type GetAlbumsParams = {
+  limit?: number;
+  offset?: number;
+  genre?: string;
+};
+
+export class AlbumNamespace {
+  constructor(private readonly call: Call) {}
+
+  getAlbum<T = unknown>(params: UriParam, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.album.getAlbum", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getAlbums<T = unknown>(params: GetAlbumsParams = {}, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.album.getAlbums", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getAlbumTracks<T = unknown>(params: UriParam, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.album.getAlbumTracks", "GET", {
+      params,
+      ...opts,
+    });
+  }
+}

package/src/namespaces/apikey.ts

@@ -0,0 +1,50 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export type ListApikeysParams = { limit?: number; offset?: number };
+export type CreateApikeyInput = { name: string; description?: string };
+export type UpdateApikeyInput = {
+  id: string;
+  name: string;
+  description?: string;
+};
+export type RemoveApikeyParams = { id: string };
+
+export class ApikeyNamespace {
+  constructor(private readonly call: Call) {}
+
+  getApikeys<T = unknown>(
+    params: ListApikeysParams = {},
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.apikey.getApikeys", "GET", {
+      params,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  createApikey<T = unknown>(input: CreateApikeyInput, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.apikey.createApikey", "POST", {
+      body: input,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  updateApikey<T = unknown>(input: UpdateApikeyInput, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.apikey.updateApikey", "POST", {
+      body: input,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  removeApikey<T = unknown>(params: RemoveApikeyParams, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.apikey.removeApikey", "POST", {
+      params,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+}

package/src/namespaces/artist.ts

@@ -0,0 +1,74 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export type UriParam = { uri: string };
+export type ArtistListenersParams = UriParam & {
+  limit?: number;
+  offset?: number;
+};
+export type GetArtistsParams = {
+  limit?: number;
+  offset?: number;
+  names?: string;
+  genre?: string;
+};
+export type GetArtistTracksParams = {
+  uri?: string;
+  limit?: number;
+  offset?: number;
+};
+
+export class ArtistNamespace {
+  constructor(private readonly call: Call) {}
+
+  getArtist<T = unknown>(params: UriParam, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.artist.getArtist", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getArtists<T = unknown>(params: GetArtistsParams = {}, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.artist.getArtists", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getArtistAlbums<T = unknown>(params: UriParam, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.artist.getArtistAlbums", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getArtistTracks<T = unknown>(
+    params: GetArtistTracksParams = {},
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.artist.getArtistTracks", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getArtistListeners<T = unknown>(
+    params: ArtistListenersParams,
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.artist.getArtistListeners", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getArtistRecentListeners<T = unknown>(
+    params: ArtistListenersParams,
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.artist.getArtistRecentListeners", "GET", {
+      params,
+      ...opts,
+    });
+  }
+}

package/src/namespaces/charts.ts

@@ -0,0 +1,47 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export type ScrobblesChartParams = {
+  did?: string;
+  artisturi?: string;
+  albumuri?: string;
+  songuri?: string;
+  genre?: string;
+  from?: string;
+  to?: string;
+};
+
+export type TopChartParams = {
+  limit?: number;
+  offset?: number;
+  startDate?: string;
+  endDate?: string;
+};
+
+export class ChartsNamespace {
+  constructor(private readonly call: Call) {}
+
+  getScrobblesChart<T = unknown>(
+    params: ScrobblesChartParams = {},
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.charts.getScrobblesChart", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getTopArtists<T = unknown>(params: TopChartParams = {}, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.charts.getTopArtists", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getTopTracks<T = unknown>(params: TopChartParams = {}, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.charts.getTopTracks", "GET", {
+      params,
+      ...opts,
+    });
+  }
+}

package/src/namespaces/dropbox.ts

@@ -0,0 +1,47 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export class DropboxNamespace {
+  constructor(private readonly call: Call) {}
+
+  getFiles<T = unknown>(
+    params: { at?: string } = {},
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.dropbox.getFiles", "GET", {
+      params,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  getMetadata<T = unknown>(params: { path: string }, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.dropbox.getMetadata", "GET", {
+      params,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  getTemporaryLink<T = unknown>(
+    params: { path: string },
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.dropbox.getTemporaryLink", "GET", {
+      params,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  downloadFile<T = unknown>(
+    params: { fileId: string },
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.dropbox.downloadFile", "GET", {
+      params,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+}