@rocksky/sdk 0.1.0

package/src/namespaces/song.ts

@@ -0,0 +1,81 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export type GetSongParams = {
+  uri?: string;
+  mbid?: string;
+  isrc?: string;
+  spotifyId?: string;
+};
+
+export type GetSongsParams = GetSongParams & {
+  limit?: number;
+  offset?: number;
+  genre?: string;
+};
+
+export type MatchSongParams = {
+  title: string;
+  artist: string;
+  mbId?: string;
+  isrc?: string;
+};
+
+export type CreateSongInput = {
+  title: string;
+  artist: string;
+  albumArtist: string;
+  album: string;
+  duration?: number;
+  mbId?: string;
+  isrc?: string;
+  albumArt?: string;
+  trackNumber?: number;
+  releaseDate?: string;
+  year?: number;
+  discNumber?: number;
+  lyrics?: string;
+};
+
+export class SongNamespace {
+  constructor(private readonly call: Call) {}
+
+  getSong<T = unknown>(params: GetSongParams, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.song.getSong", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getSongs<T = unknown>(params: GetSongsParams = {}, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.song.getSongs", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getSongRecentListeners<T = unknown>(
+    params: { uri: string; limit?: number; offset?: number },
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.song.getSongRecentListeners", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  matchSong<T = unknown>(params: MatchSongParams, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.song.matchSong", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  createSong<T = unknown>(input: CreateSongInput, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.song.createSong", "POST", {
+      body: input,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+}

package/src/namespaces/spotify.ts

@@ -0,0 +1,52 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export class SpotifyNamespace {
+  constructor(private readonly call: Call) {}
+
+  getCurrentlyPlaying<T = unknown>(
+    params: { actor?: string } = {},
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.spotify.getCurrentlyPlaying", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  play<T = unknown>(opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.spotify.play", "POST", {
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  pause<T = unknown>(opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.spotify.pause", "POST", {
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  next<T = unknown>(opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.spotify.next", "POST", {
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  previous<T = unknown>(opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.spotify.previous", "POST", {
+      requireAuth: true,
+      ...opts,
+    });
+  }
+
+  seek<T = unknown>(params: { position: number }, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.spotify.seek", "POST", {
+      params,
+      requireAuth: true,
+      ...opts,
+    });
+  }
+}

package/src/namespaces/stats.ts

@@ -0,0 +1,23 @@
+import type { Call } from "./_helpers";
+import type { RequestOptions } from "../types";
+
+export class StatsNamespace {
+  constructor(private readonly call: Call) {}
+
+  getStats<T = unknown>(params: { did: string }, opts?: RequestOptions) {
+    return this.call<T>("app.rocksky.stats.getStats", "GET", {
+      params,
+      ...opts,
+    });
+  }
+
+  getWrapped<T = unknown>(
+    params: { did: string; year?: number },
+    opts?: RequestOptions,
+  ) {
+    return this.call<T>("app.rocksky.stats.getWrapped", "GET", {
+      params,
+      ...opts,
+    });
+  }
+}

package/src/paginate.ts

@@ -0,0 +1,90 @@
+export type PageOpts = {
+  limit: number;
+  offset: number;
+  cursor?: string;
+};
+
+export type PageResult<T> = {
+  items: T[];
+  cursor?: string;
+};
+
+export type PaginateArgs<T> = {
+  /**
+   * Fetch one page. Return either:
+   *   - an array of items (offset/limit mode — pagination stops when an empty
+   *     page or a short page comes back), or
+   *   - a `{ items, cursor }` object (cursor mode — pagination stops when
+   *     `cursor` is missing/null).
+   */
+  fetch: (opts: PageOpts) => Promise<PageResult<T> | T[]>;
+  pageSize?: number;
+  maxItems?: number;
+  signal?: AbortSignal;
+};
+
+/**
+ * Page through an XRPC endpoint as an async iterable.
+ *
+ *   for await (const s of paginate({
+ *     fetch: ({ limit, offset }) =>
+ *       client.actor.getActorScrobbles({ did, limit, offset }),
+ *     pageSize: 50,
+ *   })) {
+ *     console.log(s.track.title);
+ *   }
+ */
+export function paginate<T>(args: PaginateArgs<T>): AsyncIterable<T> & {
+  /** Collect every item into an array — convenience for small result sets. */
+  toArray(): Promise<T[]>;
+} {
+  const pageSize = args.pageSize ?? 50;
+  const maxItems = args.maxItems ?? Number.POSITIVE_INFINITY;
+
+  async function* iter(): AsyncGenerator<T> {
+    let offset = 0;
+    let cursor: string | undefined;
+    let yielded = 0;
+    while (yielded < maxItems) {
+      checkAbort(args.signal);
+      const result = await args.fetch({ limit: pageSize, offset, cursor });
+      checkAbort(args.signal);
+      const { items, nextCursor } = normalize(result);
+      if (items.length === 0) return;
+      for (const item of items) {
+        if (yielded >= maxItems) return;
+        yield item;
+        yielded++;
+      }
+      offset += items.length;
+      if (nextCursor !== undefined) {
+        if (nextCursor === cursor || nextCursor === null) return;
+        cursor = nextCursor ?? undefined;
+      } else if (items.length < pageSize) {
+        return;
+      }
+    }
+  }
+
+  const iterable: AsyncIterable<T> = { [Symbol.asyncIterator]: iter };
+  return Object.assign(iterable, {
+    async toArray(): Promise<T[]> {
+      const out: T[] = [];
+      for await (const item of iter()) out.push(item);
+      return out;
+    },
+  });
+}
+
+function normalize<T>(
+  result: PageResult<T> | T[],
+): { items: T[]; nextCursor?: string | null } {
+  if (Array.isArray(result)) return { items: result };
+  return { items: result.items, nextCursor: result.cursor ?? null };
+}
+
+function checkAbort(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException("aborted", "AbortError");
+  }
+}

package/src/pipe.ts

@@ -0,0 +1,146 @@
+import { RockskyTimeoutError } from "./errors";
+
+/**
+ * Compose async operators.
+ *
+ *   const handle = await pipe(
+ *     () => client.actor.getProfile({ did }),  // thunk — withRetry can re-invoke
+ *     withRetry(3),
+ *     withTimeout(5_000),
+ *     tap(p => console.log("got", p.handle)),
+ *     map(p => p.handle.toUpperCase()),
+ *   );
+ *
+ * `pipe` accepts either a thunk `() => Promise<T>` or a bare `Promise<T>`.
+ * Operators take a factory so they can re-invoke the upstream chain (for
+ * retry). If you pass a bare Promise, the work has already started and
+ * `withRetry` becomes a no-op — pass a thunk if you want true retries.
+ */
+export type Op<A, B> = (factory: () => Promise<A>) => () => Promise<B>;
+
+type AnyOp = Op<any, any>;
+type Source<A> = Promise<A> | (() => Promise<A>);
+
+export function pipe<A>(value: Source<A>): Promise<A>;
+export function pipe<A, B>(value: Source<A>, op1: Op<A, B>): Promise<B>;
+export function pipe<A, B, C>(
+  value: Source<A>,
+  op1: Op<A, B>,
+  op2: Op<B, C>,
+): Promise<C>;
+export function pipe<A, B, C, D>(
+  value: Source<A>,
+  op1: Op<A, B>,
+  op2: Op<B, C>,
+  op3: Op<C, D>,
+): Promise<D>;
+export function pipe<A, B, C, D, E>(
+  value: Source<A>,
+  op1: Op<A, B>,
+  op2: Op<B, C>,
+  op3: Op<C, D>,
+  op4: Op<D, E>,
+): Promise<E>;
+export function pipe<A, B, C, D, E, F>(
+  value: Source<A>,
+  op1: Op<A, B>,
+  op2: Op<B, C>,
+  op3: Op<C, D>,
+  op4: Op<D, E>,
+  op5: Op<E, F>,
+): Promise<F>;
+export function pipe(
+  value: Source<unknown>,
+  ...ops: AnyOp[]
+): Promise<unknown> {
+  let factory: () => Promise<unknown> =
+    typeof value === "function" ? (value as () => Promise<unknown>) : () => value;
+  for (const op of ops) factory = op(factory);
+  return factory();
+}
+
+export function map<A, B>(fn: (a: A) => B | Promise<B>): Op<A, B> {
+  return (factory) => async () => fn(await factory());
+}
+
+export function tap<A>(fn: (a: A) => unknown | Promise<unknown>): Op<A, A> {
+  return (factory) => async () => {
+    const a = await factory();
+    await fn(a);
+    return a;
+  };
+}
+
+export function withRetry<A>(
+  times: number,
+  options: {
+    delayMs?: number;
+    factor?: number;
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+  } = {},
+): Op<A, A> {
+  const delayMs = options.delayMs ?? 200;
+  const factor = options.factor ?? 2;
+  const shouldRetry = options.shouldRetry ?? (() => true);
+  return (factory) => async () => {
+    let lastErr: unknown;
+    for (let attempt = 0; attempt <= times; attempt++) {
+      try {
+        return await factory();
+      } catch (err) {
+        lastErr = err;
+        if (attempt === times || !shouldRetry(err, attempt)) throw err;
+        await sleep(delayMs * Math.pow(factor, attempt));
+      }
+    }
+    throw lastErr;
+  };
+}
+
+export function withTimeout<A>(ms: number): Op<A, A> {
+  return (factory) => () =>
+    new Promise<A>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new RockskyTimeoutError(ms)),
+        ms,
+      );
+      factory().then(
+        (v) => {
+          clearTimeout(timer);
+          resolve(v);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+      );
+    });
+}
+
+export function withFallback<A>(fallback: A | ((err: unknown) => A | Promise<A>)): Op<A, A> {
+  return (factory) => async () => {
+    try {
+      return await factory();
+    } catch (err) {
+      return typeof fallback === "function"
+        ? await (fallback as (e: unknown) => A | Promise<A>)(err)
+        : fallback;
+    }
+  };
+}
+
+export function catchError<A, B>(
+  handler: (err: unknown) => B | Promise<B>,
+): Op<A, A | B> {
+  return (factory) => async () => {
+    try {
+      return await factory();
+    } catch (err) {
+      return await handler(err);
+    }
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}