@rocksky/sdk 0.11.0 → 0.13.0

package/dist/index.js

@@ -187,9 +187,9 @@ var init_library = __esm(() => {
 // src/client.ts
 var exports_client = {};
 __export(exports_client, {
-  RockskyClient: () => RockskyClient,
+  DEFAULT_APPVIEW: () => DEFAULT_APPVIEW,
   Interval: () => Interval,
-  DEFAULT_APPVIEW: () => DEFAULT_APPVIEW
+  RockskyClient: () => RockskyClient
 });
 import { Client, simpleFetchHandler } from "@atcute/client";
 function since(days = 0, months = 0, years = 0) {
@@ -297,27 +297,30 @@ class RockskyClient {
     });
     return out.artists ?? [];
   }
-  async catalogAlbums(limit = 50, offset = 0, genre) {
+  async catalogAlbums(limit = 50, offset = 0, genre, filter) {
     const out = await this.query("app.rocksky.album.getAlbums", {
       limit,
       offset,
-      genre
+      genre,
+      filter: filter?.toString()
     });
     return out.albums ?? [];
   }
-  async catalogArtists(limit = 50, offset = 0, genre) {
+  async catalogArtists(limit = 50, offset = 0, genre, filter) {
     const out = await this.query("app.rocksky.artist.getArtists", {
       limit,
       offset,
-      genre
+      genre,
+      filter: filter?.toString()
     });
     return out.artists ?? [];
   }
-  async catalogSongs(limit = 50, offset = 0, genre) {
+  async catalogSongs(limit = 50, offset = 0, genre, filter) {
     const out = await this.query("app.rocksky.song.getSongs", {
       limit,
       offset,
-      genre
+      genre,
+      filter: filter?.toString()
     });
     return out.tracks ?? [];
   }
@@ -337,12 +340,13 @@ class RockskyClient {
     });
     return out.tracks ?? [];
   }
-  async scrobbleFeed(did, following = false, limit = 50, offset = 0) {
+  async scrobbleFeed(did, following = false, limit = 50, offset = 0, filter) {
     const out = await this.query("app.rocksky.scrobble.getScrobbles", {
       did,
       following,
       limit,
-      offset
+      offset,
+      filter: filter?.toString()
     });
     return out.scrobbles ?? [];
   }
@@ -1160,6 +1164,8 @@ class RemotePlayer {
         duration_ms: track.durationMs ?? 0,
         album_art: track.albumArt,
         is_playing: track.isPlaying ?? true,
+        codec: track.codec,
+        sample_rate: track.sampleRate,
         device_name: this.opts.name
       }
     });
@@ -1571,6 +1577,8 @@ function trackFromJson(d) {
     durationMs: d.duration_ms ?? d.length,
     elapsedMs: d.elapsed,
     isPlaying: d.is_playing,
+    codec: d.codec,
+    sampleRate: d.sample_rate,
     songUri: d.song_uri,
     albumUri: d.album_uri,
     artistUri: d.artist_uri,
@@ -1602,26 +1610,163 @@ function deviceFromJson(d) {
     queue: (d.queue?.queue ?? []).map(queueItemFromJson)
   };
 }
+// src/filter.ts
+var SAFE_VALUE = /^[A-Za-z0-9_.:@*+-]+$/;
+var renderValue = (value) => {
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (value.length > 0 && SAFE_VALUE.test(value))
+    return value;
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+};
+
+class Filter {
+  expr;
+  kind;
+  constructor(expr, kind) {
+    this.expr = expr;
+    this.kind = kind;
+  }
+  static comparison(field, op, value) {
+    return new Filter(`${field}${op}${renderValue(value)}`, "comparison");
+  }
+  static list(field, op, values) {
+    if (values.length === 0) {
+      throw new Error(`Filter.${op === "=in=" ? "in" : "out"}("${field}", ...) needs at least one value`);
+    }
+    return new Filter(`${field}${op}(${values.map(renderValue).join(",")})`, "comparison");
+  }
+  static eq(field, value) {
+    return Filter.comparison(field, "==", value);
+  }
+  static ne(field, value) {
+    return Filter.comparison(field, "!=", value);
+  }
+  static gt(field, value) {
+    return Filter.comparison(field, "=gt=", value);
+  }
+  static ge(field, value) {
+    return Filter.comparison(field, "=ge=", value);
+  }
+  static lt(field, value) {
+    return Filter.comparison(field, "=lt=", value);
+  }
+  static le(field, value) {
+    return Filter.comparison(field, "=le=", value);
+  }
+  static in(field, values) {
+    return Filter.list(field, "=in=", values);
+  }
+  static out(field, values) {
+    return Filter.list(field, "=out=", values);
+  }
+  static isNull(field) {
+    return new Filter(`${field}==null`, "comparison");
+  }
+  static isNotNull(field) {
+    return new Filter(`${field}!=null`, "comparison");
+  }
+  and(other) {
+    return new Filter(`${this.renderIn("and")};${other.renderIn("and")}`, "and");
+  }
+  or(other) {
+    return new Filter(`${this.expr},${other.expr}`, "or");
+  }
+  renderIn(parent) {
+    return this.kind === "or" ? `(${this.expr})` : this.expr;
+  }
+  build() {
+    return this.expr;
+  }
+  toString() {
+    return this.expr;
+  }
+}
+var SongFields = {
+  title: "title",
+  artist: "artist",
+  album: "album",
+  albumArtist: "albumArtist",
+  genre: "genre",
+  composer: "composer",
+  label: "label",
+  duration: "duration",
+  trackNumber: "trackNumber",
+  discNumber: "discNumber",
+  mbId: "mbId",
+  isrc: "isrc",
+  sha256: "sha256",
+  uri: "uri",
+  albumUri: "albumUri",
+  artistUri: "artistUri",
+  createdAt: "createdAt"
+};
+var AlbumFields = {
+  title: "title",
+  artist: "artist",
+  year: "year",
+  releaseDate: "releaseDate",
+  sha256: "sha256",
+  uri: "uri",
+  artistUri: "artistUri",
+  createdAt: "createdAt"
+};
+var ArtistFields = {
+  name: "name",
+  genres: "genres",
+  bornIn: "bornIn",
+  born: "born",
+  died: "died",
+  sha256: "sha256",
+  uri: "uri",
+  createdAt: "createdAt"
+};
+var ScrobbleFields = {
+  uri: "uri",
+  date: "date",
+  timestamp: "timestamp",
+  title: "title",
+  artist: "artist",
+  album: "album",
+  trackTitle: "track.title",
+  trackArtist: "track.artist",
+  trackAlbum: "track.album",
+  trackAlbumArtist: "track.albumArtist",
+  trackGenre: "track.genre",
+  trackDuration: "track.duration",
+  trackIsrc: "track.isrc",
+  trackMbId: "track.mbId",
+  userDid: "user.did",
+  userHandle: "user.handle",
+  userDisplayName: "user.displayName",
+  artistName: "artist.name",
+  artistGenres: "artist.genres"
+};
 
 // src/index.ts
 init_errors();
 export {
-  totalIndexed,
-  songHash,
-  runJetstream,
-  artistHash,
-  albumHash,
-  RockskyLibrary,
-  RockskyIndex,
-  RockskyError,
-  RockskyClient,
-  RemotePlayer,
-  RemoteController,
-  MAX_SAFE_WRITES_PER_HOUR,
-  Interval,
-  DEFAULT_REMOTE_WS,
-  DEFAULT_MATCH_SONG_PER_HOUR,
-  DEFAULT_JETSTREAM_SERVERS,
+  Agent,
+  AlbumFields,
+  ArtistFields,
   DEFAULT_APPVIEW,
-  Agent
+  DEFAULT_JETSTREAM_SERVERS,
+  DEFAULT_MATCH_SONG_PER_HOUR,
+  DEFAULT_REMOTE_WS,
+  Filter,
+  Interval,
+  MAX_SAFE_WRITES_PER_HOUR,
+  RemoteController,
+  RemotePlayer,
+  RockskyClient,
+  RockskyError,
+  RockskyIndex,
+  RockskyLibrary,
+  ScrobbleFields,
+  SongFields,
+  albumHash,
+  artistHash,
+  runJetstream,
+  songHash,
+  totalIndexed
 };

package/dist/remote-player.d.ts

@@ -34,6 +34,11 @@ export interface RemoteNowPlaying {
     /** Current position, ms. */
     elapsedMs?: number;
     isPlaying?: boolean;
+    /** Audio codec / container of the playing file (e.g. "mp3", "flac"),
+     *  when the player knows it. Shown as a format badge by controller UIs. */
+    codec?: string;
+    /** Audio sample rate in Hz (e.g. 44100), when the player knows it. */
+    sampleRate?: number;
     /** The song's `at://` URI. */
     songUri?: string;
     /** The album's `at://` URI. */

package/dist/remote-player.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-player.d.ts","sourceRoot":"","sources":["../src/remote-player.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"remote-player.d.ts","sourceRoot":"","sources":["../src/remote-player.ts"],"names":[],"mappings":"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"}

package/dist/remote.js

@@ -80,6 +80,8 @@ class RemotePlayer {
         duration_ms: track.durationMs ?? 0,
         album_art: track.albumArt,
         is_playing: track.isPlaying ?? true,
+        codec: track.codec,
+        sample_rate: track.sampleRate,
         device_name: this.opts.name
       }
     });
@@ -491,6 +493,8 @@ function trackFromJson(d) {
     durationMs: d.duration_ms ?? d.length,
     elapsedMs: d.elapsed,
     isPlaying: d.is_playing,
+    codec: d.codec,
+    sampleRate: d.sample_rate,
     songUri: d.song_uri,
     albumUri: d.album_uri,
     artistUri: d.artist_uri,
@@ -523,7 +527,7 @@ function deviceFromJson(d) {
   };
 }
 export {
-  RemotePlayer,
+  DEFAULT_REMOTE_WS,
   RemoteController,
-  DEFAULT_REMOTE_WS
+  RemotePlayer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocksky/sdk",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "TypeScript SDK for Rocksky — built on atcute: AppView reads, AT Protocol PDS writes (scrobble, like, follow, shout), a local dedup index, and Jetstream real-time sync.",
   "license": "MIT",
   "repository": {

package/src/client.ts

@@ -1,6 +1,7 @@
 import { Client, simpleFetchHandler } from "@atcute/client";
 
 import { RockskyError } from "./errors.js";
+import type { Filter } from "./filter.js";
 import { RockskyLibrary } from "./library.js";
 import type {
   ActorProfileViewBasic,
@@ -229,32 +230,53 @@ export class RockskyClient {
     return out.artists ?? [];
   }
 
-  /** The album catalog, optionally filtered by `genre`. */
-  async catalogAlbums(limit = 50, offset = 0, genre?: string): Promise<AlbumViewBasic[]> {
+  /** The album catalog, optionally filtered by `genre` and/or an RSQL
+   * {@link Filter} expression (see {@link AlbumFields}). */
+  async catalogAlbums(
+    limit = 50,
+    offset = 0,
+    genre?: string,
+    filter?: string | Filter,
+  ): Promise<AlbumViewBasic[]> {
     const out = await this.query<{ albums?: AlbumViewBasic[] }>("app.rocksky.album.getAlbums", {
       limit,
       offset,
       genre,
+      filter: filter?.toString(),
     });
     return out.albums ?? [];
   }
 
-  /** The artist catalog, optionally filtered by `genre`. */
-  async catalogArtists(limit = 50, offset = 0, genre?: string): Promise<ArtistViewBasic[]> {
+  /** The artist catalog, optionally filtered by `genre` and/or an RSQL
+   * {@link Filter} expression (see {@link ArtistFields}). */
+  async catalogArtists(
+    limit = 50,
+    offset = 0,
+    genre?: string,
+    filter?: string | Filter,
+  ): Promise<ArtistViewBasic[]> {
     const out = await this.query<{ artists?: ArtistViewBasic[] }>("app.rocksky.artist.getArtists", {
       limit,
       offset,
       genre,
+      filter: filter?.toString(),
     });
     return out.artists ?? [];
   }
 
-  /** The song catalog, optionally filtered by `genre`. */
-  async catalogSongs(limit = 50, offset = 0, genre?: string): Promise<SongViewBasic[]> {
+  /** The song catalog, optionally filtered by `genre` and/or an RSQL
+   * {@link Filter} expression (see {@link SongFields}). */
+  async catalogSongs(
+    limit = 50,
+    offset = 0,
+    genre?: string,
+    filter?: string | Filter,
+  ): Promise<SongViewBasic[]> {
     const out = await this.query<{ tracks?: SongViewBasic[] }>("app.rocksky.song.getSongs", {
       limit,
       offset,
       genre,
+      filter: filter?.toString(),
     });
     return out.tracks ?? [];
   }
@@ -282,13 +304,21 @@ export class RockskyClient {
   }
 
   /** A social/global scrobbles feed. Pass `did` to scope to an actor and
-   * `following = true` for their follow graph. */
-  async scrobbleFeed(did?: string, following = false, limit = 50, offset = 0): Promise<ScrobbleViewBasic[]> {
+   * `following = true` for their follow graph. `filter` takes an RSQL
+   * {@link Filter} expression (see {@link ScrobbleFields}). */
+  async scrobbleFeed(
+    did?: string,
+    following = false,
+    limit = 50,
+    offset = 0,
+    filter?: string | Filter,
+  ): Promise<ScrobbleViewBasic[]> {
     const out = await this.query<{ scrobbles?: ScrobbleViewBasic[] }>("app.rocksky.scrobble.getScrobbles", {
       did,
       following,
       limit,
       offset,
+      filter: filter?.toString(),
     });
     return out.scrobbles ?? [];
   }

package/src/filter.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { AlbumFields, ArtistFields, Filter, ScrobbleFields, SongFields } from "./filter.js";
+
+describe("Filter", () => {
+  test("eq renders a bare value when safe", () => {
+    expect(Filter.eq("artist", "Radiohead").build()).toBe("artist==Radiohead");
+  });
+
+  test("eq quotes values with spaces", () => {
+    expect(Filter.eq("artist", "Daft Punk").build()).toBe('artist=="Daft Punk"');
+  });
+
+  test("eq escapes embedded quotes and backslashes", () => {
+    expect(Filter.eq("title", 'He said "hi"').build()).toBe('title=="He said \\"hi\\""');
+    expect(Filter.eq("title", "back\\slash").build()).toBe('title=="back\\\\slash"');
+  });
+
+  test("wildcards pass through unquoted", () => {
+    expect(Filter.eq("artist", "Daft*").build()).toBe("artist==Daft*");
+  });
+
+  test("ne", () => {
+    expect(Filter.ne("artist", "Eminem").build()).toBe("artist!=Eminem");
+  });
+
+  test("ordered comparisons render verbose operators", () => {
+    expect(Filter.gt("duration", 200000).build()).toBe("duration=gt=200000");
+    expect(Filter.ge("year", 2000).build()).toBe("year=ge=2000");
+    expect(Filter.lt("trackNumber", 5).build()).toBe("trackNumber=lt=5");
+    expect(Filter.le("year", 1999).build()).toBe("year=le=1999");
+  });
+
+  test("in and out lists", () => {
+    expect(Filter.in("genre", ["house", "electro"]).build()).toBe("genre=in=(house,electro)");
+    expect(Filter.out("genre", ["hip hop"]).build()).toBe('genre=out=("hip hop")');
+  });
+
+  test("in/out reject empty lists", () => {
+    expect(() => Filter.in("genre", [])).toThrow();
+    expect(() => Filter.out("genre", [])).toThrow();
+  });
+
+  test("null checks", () => {
+    expect(Filter.isNull("uri").build()).toBe("uri==null");
+    expect(Filter.isNotNull("uri").build()).toBe("uri!=null");
+  });
+
+  test("and joins with ;", () => {
+    const f = Filter.eq("artist", "Radiohead").and(Filter.gt("duration", 200000));
+    expect(f.build()).toBe("artist==Radiohead;duration=gt=200000");
+  });
+
+  test("or joins with ,", () => {
+    const f = Filter.eq("artist", "Radiohead").or(Filter.eq("artist", "Muse"));
+    expect(f.build()).toBe("artist==Radiohead,artist==Muse");
+  });
+
+  test("or nested in and is parenthesized", () => {
+    const left = Filter.eq("artist", "Radiohead").or(Filter.eq("artist", "Muse"));
+    expect(left.and(Filter.gt("duration", 200000)).build()).toBe(
+      "(artist==Radiohead,artist==Muse);duration=gt=200000",
+    );
+    const right = Filter.eq("genre", "house").or(Filter.eq("genre", "electro"));
+    expect(Filter.eq("artist", "Radiohead").and(right).build()).toBe(
+      "artist==Radiohead;(genre==house,genre==electro)",
+    );
+  });
+
+  test("and nested in or needs no parentheses", () => {
+    const f = Filter.eq("artist", "Radiohead")
+      .and(Filter.gt("duration", 200000))
+      .or(Filter.eq("genre", "house"));
+    expect(f.build()).toBe("artist==Radiohead;duration=gt=200000,genre==house");
+  });
+
+  test("booleans and dotted fields", () => {
+    expect(Filter.eq("user.handle", "tsiry.dev").build()).toBe("user.handle==tsiry.dev");
+    expect(Filter.eq("liked", true).build()).toBe("liked==true");
+  });
+
+  test("toString matches build so filters interpolate", () => {
+    const f = Filter.eq("artist", "Radiohead");
+    expect(`${f}`).toBe(f.build());
+  });
+
+  test("field constants map to server selectors", () => {
+    expect(SongFields.albumArtist).toBe("albumArtist");
+    expect(AlbumFields.releaseDate).toBe("releaseDate");
+    expect(ArtistFields.genres).toBe("genres");
+    expect(ScrobbleFields.trackArtist).toBe("track.artist");
+    expect(ScrobbleFields.userHandle).toBe("user.handle");
+    expect(Filter.eq(ScrobbleFields.artistGenres, "house").build()).toBe("artist.genres==house");
+  });
+});