@rocksky/sdk 0.11.0 → 0.13.0

package/src/filter.ts

@@ -0,0 +1,192 @@
+/**
+ * Fluent builder for RSQL filter expressions, accepted by the `filter`
+ * parameter of the catalog and scrobble-feed queries
+ * (app.rocksky.song.getSongs, app.rocksky.artist.getArtists,
+ * app.rocksky.album.getAlbums, app.rocksky.scrobble.getScrobbles).
+ *
+ * ```ts
+ * import { Filter } from "@rocksky/sdk";
+ *
+ * const filter = Filter.eq("artist", "Daft Punk")
+ *   .and(Filter.gt("duration", 200_000))
+ *   .or(Filter.in("genre", ["house", "electro"]));
+ *
+ * await client.catalogSongs(50, 0, undefined, filter);
+ * // artist=="Daft Punk";duration=gt=200000,genre=in=(house,electro)
+ * ```
+ *
+ * String values are quoted and escaped automatically when they contain
+ * characters RSQL reserves; `*` wildcards pass through unquoted so
+ * `Filter.eq("artist", "Daft*")` performs a case-insensitive match.
+ */
+export type FilterValue = string | number | boolean;
+
+/** Characters that never need quoting in an RSQL value (`*` kept bare so wildcards work). */
+const SAFE_VALUE = /^[A-Za-z0-9_.:@*+-]+$/;
+
+const renderValue = (value: FilterValue): string => {
+  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, '\\"')}"`;
+};
+
+type NodeKind = "comparison" | "and" | "or";
+
+export class Filter {
+  private constructor(
+    private readonly expr: string,
+    private readonly kind: NodeKind,
+  ) {}
+
+  private static comparison(field: string, op: string, value: FilterValue): Filter {
+    return new Filter(`${field}${op}${renderValue(value)}`, "comparison");
+  }
+
+  private static list(field: string, op: string, values: FilterValue[]): Filter {
+    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");
+  }
+
+  /** `field==value` — equals; `*` in string values is a wildcard. */
+  static eq(field: string, value: FilterValue): Filter {
+    return Filter.comparison(field, "==", value);
+  }
+
+  /** `field!=value` — not equals. */
+  static ne(field: string, value: FilterValue): Filter {
+    return Filter.comparison(field, "!=", value);
+  }
+
+  /** `field=gt=value` — greater than. */
+  static gt(field: string, value: FilterValue): Filter {
+    return Filter.comparison(field, "=gt=", value);
+  }
+
+  /** `field=ge=value` — greater than or equal. */
+  static ge(field: string, value: FilterValue): Filter {
+    return Filter.comparison(field, "=ge=", value);
+  }
+
+  /** `field=lt=value` — less than. */
+  static lt(field: string, value: FilterValue): Filter {
+    return Filter.comparison(field, "=lt=", value);
+  }
+
+  /** `field=le=value` — less than or equal. */
+  static le(field: string, value: FilterValue): Filter {
+    return Filter.comparison(field, "=le=", value);
+  }
+
+  /** `field=in=(a,b)` — matches any of the values. */
+  static in(field: string, values: FilterValue[]): Filter {
+    return Filter.list(field, "=in=", values);
+  }
+
+  /** `field=out=(a,b)` — matches none of the values. */
+  static out(field: string, values: FilterValue[]): Filter {
+    return Filter.list(field, "=out=", values);
+  }
+
+  /** `field==null` — the field is NULL. */
+  static isNull(field: string): Filter {
+    return new Filter(`${field}==null`, "comparison");
+  }
+
+  /** `field!=null` — the field is not NULL. */
+  static isNotNull(field: string): Filter {
+    return new Filter(`${field}!=null`, "comparison");
+  }
+
+  /** Both sides must match (`;`). An `or` operand is parenthesized to keep RSQL precedence. */
+  and(other: Filter): Filter {
+    return new Filter(`${this.renderIn("and")};${other.renderIn("and")}`, "and");
+  }
+
+  /** Either side may match (`,`). */
+  or(other: Filter): Filter {
+    return new Filter(`${this.expr},${other.expr}`, "or");
+  }
+
+  private renderIn(parent: "and"): string {
+    return this.kind === "or" ? `(${this.expr})` : this.expr;
+  }
+
+  /** The RSQL expression string to send as the `filter` query param. */
+  build(): string {
+    return this.expr;
+  }
+
+  toString(): string {
+    return this.expr;
+  }
+}
+
+/** Filterable fields of app.rocksky.song.getSongs. */
+export const 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",
+} as const;
+
+/** Filterable fields of app.rocksky.album.getAlbums. */
+export const AlbumFields = {
+  title: "title",
+  artist: "artist",
+  year: "year",
+  releaseDate: "releaseDate",
+  sha256: "sha256",
+  uri: "uri",
+  artistUri: "artistUri",
+  createdAt: "createdAt",
+} as const;
+
+/** Filterable fields of app.rocksky.artist.getArtists. */
+export const ArtistFields = {
+  name: "name",
+  genres: "genres",
+  bornIn: "bornIn",
+  born: "born",
+  died: "died",
+  sha256: "sha256",
+  uri: "uri",
+  createdAt: "createdAt",
+} as const;
+
+/** Filterable fields of app.rocksky.scrobble.getScrobbles (dotted selectors reach the joined track/user/artist). */
+export const 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",
+} as const;

package/src/generated/types.ts

@@ -243,6 +243,8 @@ export interface ArtistGetArtistsParams {
   names?: string;
   /** The genre to filter artists by */
   genre?: string;
+  /** RSQL filter expression, e.g. `name==Daft*;genres=in=(house,electro)`. Supports ==, !=, <, <=, >, >=, =in=, =out=, and `;`/`and`, `,`/`or` combinators, `*` wildcards in string values. Filterable fields: name, genres, bornIn, born, died, sha256, uri, createdAt */
+  filter?: string;
 }
 
 export interface ArtistListenerViewBasic {
@@ -847,6 +849,8 @@ export interface GetAlbumsParams {
   offset?: number;
   /** The genre to filter artists by */
   genre?: string;
+  /** RSQL filter expression, e.g. `artist=="Daft Punk";year=ge=2000`. Supports ==, !=, <, <=, >, >=, =in=, =out=, and `;`/`and`, `,`/`or` combinators, `*` wildcards in string values. Filterable fields: title, artist, year, releaseDate, sha256, uri, artistUri, createdAt */
+  filter?: string;
 }
 
 export interface GetAlbumTracksOutput {
@@ -1243,6 +1247,8 @@ export interface GetScrobblesParams {
   limit?: number;
   /** The offset for pagination */
   offset?: number;
+  /** RSQL filter expression, e.g. `track.artist=="Daft Punk";date=ge=2025-01-01`. Supports ==, !=, <, <=, >, >=, =in=, =out=, and `;`/`and`, `,`/`or` combinators, `*` wildcards in string values. Filterable fields: uri, date, timestamp, title, artist, album, track.title, track.artist, track.album, track.albumArtist, track.genre, track.duration, track.isrc, track.mbId, user.did, user.handle, user.displayName, artist.name, artist.genres */
+  filter?: string;
 }
 
 export interface GetShoutRepliesOutput {
@@ -1312,6 +1318,8 @@ export interface GetSongsParams {
   isrc?: string;
   /** Filter songs by Spotify track ID (resolved internally to the Spotify track URL) */
   spotifyId?: string;
+  /** RSQL filter expression, e.g. `artist=="Daft Punk";duration=gt=200000`. Supports ==, !=, <, <=, >, >=, =in=, =out=, and `;`/`and`, `,`/`or` combinators, `*` wildcards in string values. Filterable fields: title, artist, album, albumArtist, genre, composer, label, duration, trackNumber, discNumber, mbId, isrc, sha256, uri, albumUri, artistUri, createdAt */
+  filter?: string;
 }
 
 export interface GetStarredOutput {
@@ -1626,6 +1634,18 @@ export interface NotificationActor {
   avatar?: Uri;
 }
 
+/** The song, album, or scrobble a notification relates to, for rich display. */
+export interface NotificationSubjectView {
+  /** The at-uri of the subject. */
+  uri: string;
+  /** The title of the track or album. */
+  title?: string;
+  /** The artist of the track or album. */
+  artist?: string;
+  /** The album art image URL. */
+  albumArt?: Uri;
+}
+
 export interface NotificationView {
   /** The unique identifier of the notification. */
   id: string;
@@ -1642,6 +1662,7 @@ export interface NotificationView {
   /** The content of the related shout, if any. */
   shoutContent?: string;
   actor?: NotificationActor;
+  subject?: NotificationSubjectView;
 }
 
 export interface PingOutput {

package/src/index.ts

@@ -41,6 +41,14 @@ export {
   type RemoteDevice,
   type RemoteStatus,
 } from "./remote-controller.js";
+export {
+  Filter,
+  SongFields,
+  AlbumFields,
+  ArtistFields,
+  ScrobbleFields,
+  type FilterValue,
+} from "./filter.js";
 export { songHash, albumHash, artistHash } from "./hash.js";
 export { RockskyError } from "./errors.js";
 export type * from "./generated/types.js";

package/src/remote-controller.ts

@@ -332,6 +332,8 @@ function trackFromJson(d: Json): RemoteNowPlaying {
     durationMs: d.duration_ms ?? d.length,
     elapsedMs: d.elapsed,
     isPlaying: d.is_playing,
+    codec: d.codec,
+    sampleRate: d.sample_rate,
     // Server-enriched fields (present on the broadcast a controller receives).
     songUri: d.song_uri,
     albumUri: d.album_uri,

package/src/remote-player.ts

@@ -36,6 +36,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 following are filled in by the server on the broadcast a controller
   // receives (a player leaves them unset — the server resolves them from the
   // library). They let a controller UI deep-link and show like state.
@@ -186,6 +191,8 @@ export 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,
       },
     });