@rocksky/sdk 0.13.0 → 0.14.1

package/src/client.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { RockskyClient } from "./client.js";
+
+const TOKEN = "test-token";
+
+/**
+ * Swap in a fetch that records the request instead of making one. The client
+ * builds its fetch handler in the constructor, so install this first.
+ */
+function captureFetch(): {
+	calls: Request[];
+	only: () => Request;
+	restore: () => void;
+} {
+	const calls: Request[] = [];
+	const real = globalThis.fetch;
+	globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+		calls.push(new Request(input as RequestInfo, init));
+		return new Response(JSON.stringify({ status: "ok" }), {
+			status: 200,
+			headers: { "content-type": "application/json" },
+		});
+	}) as typeof globalThis.fetch;
+	return {
+		calls,
+		/** The single request that was made; fails loudly if there wasn't exactly one. */
+		only: () => {
+			expect(calls).toHaveLength(1);
+			return calls[0] as Request;
+		},
+		restore: () => {
+			globalThis.fetch = real;
+		},
+	};
+}
+
+let restore: (() => void) | null = null;
+afterEach(() => {
+	restore?.();
+	restore = null;
+});
+
+describe("authenticated request headers", () => {
+	test("a JSON procedure keeps its content-type alongside the bearer token", async () => {
+		// Regression: the auth wrapper used to merge headers with an object spread.
+		// atcute passes a Headers instance, which has no own enumerable properties,
+		// so the spread produced `{}` and dropped the `application/json` content-type
+		// atcute sets for a JSON body. The AppView then saw text/plain and replied
+		// `InvalidRequest: Wrong request encoding (Content-Type): text/plain`.
+		const cap = captureFetch();
+		restore = cap.restore;
+
+		const client = new RockskyClient("https://appview.test", TOKEN);
+		await client.library().createPlaylist("Late night drive");
+
+		const req = cap.only();
+		expect(req.method).toBe("POST");
+		expect(req.headers.get("content-type")).toBe("application/json");
+		expect(req.headers.get("authorization")).toBe(`Bearer ${TOKEN}`);
+		expect(await req.json()).toEqual({ name: "Late night drive" });
+	});
+
+	test("a query still carries the bearer token", async () => {
+		const cap = captureFetch();
+		restore = cap.restore;
+
+		const client = new RockskyClient("https://appview.test", TOKEN);
+		await client.library().getPlaylists();
+
+		expect(cap.only().headers.get("authorization")).toBe(`Bearer ${TOKEN}`);
+	});
+
+	test("no token means no authorization header", async () => {
+		const cap = captureFetch();
+		restore = cap.restore;
+
+		const client = new RockskyClient("https://appview.test");
+		await client.get("app.rocksky.actor.getProfile", { did: "did:plc:test" });
+
+		expect(cap.only().headers.get("authorization")).toBeNull();
+	});
+});

package/src/client.ts

@@ -11,6 +11,8 @@ import type {
   ArtistViewBasic,
   ArtistViewDetailed,
   ChartsView,
+  CreateScrobbleInput,
+  FollowAccountOutput,
   FeedGeneratorsView,
   FeedRecommendationsView,
   FeedRecommendedAlbumsView,
@@ -37,10 +39,13 @@ import type {
   GetTrackShoutsOutput,
   GetUnreadCountOutput,
   ListNotificationsOutput,
+  MirrorSourceView,
   PlayerCurrentlyPlayingViewDetailed,
   PlayerPlaybackQueueViewDetailed,
   PlaylistGetPlaylistsOutput,
   PlaylistViewDetailed,
+  PutAudioSettingsInput,
+  PutMirrorSourceInput,
   RockboxSettingsView,
   ScrobbleViewBasic,
   SongViewBasic,
@@ -48,6 +53,10 @@ import type {
   StatsGlobalStatsView,
   StatsView,
   StatsWrappedView,
+  PlaylistCreatePlaylistOutput,
+  PlaylistUpdatePlaylistOutput,
+  AddSongsOutput,
+  UnfollowAccountOutput,
   UpdateSeenOutput,
 } from "./generated/types.js";
 
@@ -107,11 +116,16 @@ export class RockskyClient {
     let handler = simpleFetchHandler({ service: appview });
     if (token) {
       const inner = handler;
-      handler = ((pathname: string, init?: RequestInit) =>
-        inner(pathname, {
-          ...init,
-          headers: { ...(init?.headers as Record<string, string>), authorization: `Bearer ${token}` },
-        })) as typeof handler;
+      handler = ((pathname: string, init?: RequestInit) => {
+        // `new Headers(init.headers)`, not a spread: atcute hands us a Headers
+        // instance, and a Headers has no own enumerable properties — spreading
+        // it yields `{}` and silently drops everything already set. That threw
+        // away the `content-type: application/json` atcute adds for a JSON
+        // body, so the AppView saw text/plain and rejected the request.
+        const headers = new Headers(init?.headers);
+        headers.set("authorization", `Bearer ${token}`);
+        return inner(pathname, { ...init, headers });
+      }) as typeof handler;
     }
     this.rpc = new Client({ handler });
   }
@@ -136,7 +150,7 @@ export class RockskyClient {
       if (v !== undefined && v !== "") clean[k] = v;
     }
     const res = await this.rpc.get(nsid as never, { params: clean } as never);
-    if (!res.ok) throw new RockskyError(res.data);
+    if (!res.ok) throw new RockskyError(res.data, res.status);
     return res.data as T;
   }
 
@@ -161,6 +175,24 @@ export class RockskyClient {
     return this.query(nsid, params);
   }
 
+  /** Call any AppView procedure by nsid. `params` ride the query string (some
+   * procedures take their arguments there), `body` is the JSON input — omitted
+   * entirely when `undefined`. Escape hatch for procedures without a wrapper. */
+  async post<T = unknown>(
+    nsid: string,
+    opts: { params?: Record<string, unknown>; body?: unknown } = {},
+  ): Promise<T> {
+    const clean: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(opts.params ?? {})) {
+      if (v !== undefined && v !== "") clean[k] = v;
+    }
+    const call: Record<string, unknown> = { params: clean };
+    if (opts.body !== undefined) call.input = opts.body;
+    const res = await this.rpc.post(nsid as never, call as never);
+    if (!res.ok) throw new RockskyError(res.data, res.status);
+    return res.data as T;
+  }
+
   /** An actor's most-played songs. */
   async songs(actor: string, limit = 50, offset = 0): Promise<SongViewBasic[]> {
     const out = await this.query<{ tracks?: SongViewBasic[] }>("app.rocksky.actor.getActorSongs", {
@@ -492,6 +524,54 @@ export class RockskyClient {
   playlist(uri: string): Promise<PlaylistViewDetailed> {
     return this.query("app.rocksky.playlist.getPlaylist", { uri });
   }
+
+  /**
+   * Create a playlist (`app.rocksky.playlist.createPlaylist`). Auth required.
+   * Publishes an app.rocksky.playlist record to the caller's repo; the AppView
+   * only lists it once the commit has been ingested.
+   */
+  createPlaylist(input: {
+    name: string;
+    description?: string;
+    pictureUrl?: string;
+  }): Promise<PlaylistCreatePlaylistOutput> {
+    return this.post("app.rocksky.playlist.createPlaylist", { params: input });
+  }
+
+  /** Rename or re-describe a playlist (`app.rocksky.playlist.updatePlaylist`). Owner only. */
+  updatePlaylist(input: {
+    uri: string;
+    name?: string;
+    description?: string;
+    pictureUrl?: string;
+  }): Promise<PlaylistUpdatePlaylistOutput> {
+    return this.post("app.rocksky.playlist.updatePlaylist", { params: input });
+  }
+
+  /**
+   * Add songs to a playlist (`app.rocksky.playlist.addSongs`). Owner only.
+   * `songs` are app.rocksky.song AT-URIs; returns the created entry URIs.
+   */
+  addSongs(uri: string, songs: string[]): Promise<AddSongsOutput> {
+    return this.post("app.rocksky.playlist.addSongs", {
+      params: { uri, songs },
+    });
+  }
+
+  /** Delete a playlist and the caller's own entries (`app.rocksky.playlist.removePlaylist`). Owner only. */
+  removePlaylist(uri: string): Promise<void> {
+    return this.post("app.rocksky.playlist.removePlaylist", { params: { uri } });
+  }
+
+  /**
+   * Remove a song from a playlist (`app.rocksky.playlist.removeTrack`). An
+   * entry can only be retracted by the repo that published it.
+   */
+  removeTrack(uri: string, songUri: string): Promise<void> {
+    return this.post("app.rocksky.playlist.removeTrack", {
+      params: { uri, songUri },
+    });
+  }
   /** Shouts on an album. */
   albumShouts(uri: string, limit = 50, offset = 0): Promise<GetAlbumShoutsOutput> {
     return this.query("app.rocksky.shout.getAlbumShouts", { uri, limit, offset });
@@ -539,7 +619,34 @@ export class RockskyClient {
     const res = await this.rpc.post("app.rocksky.notification.updateSeen" as never, {
       input: (ids && ids.length ? { ids } : {}) as never,
     } as never);
-    if (!res.ok) throw new RockskyError(res.data);
+    if (!res.ok) throw new RockskyError(res.data, res.status);
     return res.data as UpdateSeenOutput;
   }
+
+  /** Follow an account by DID or handle (`app.rocksky.graph.followAccount`). Auth required. */
+  followAccount(account: string): Promise<FollowAccountOutput> {
+    return this.post("app.rocksky.graph.followAccount", { params: { account } });
+  }
+
+  /** Unfollow an account by DID or handle (`app.rocksky.graph.unfollowAccount`). Auth required. */
+  unfollowAccount(account: string): Promise<UnfollowAccountOutput> {
+    return this.post("app.rocksky.graph.unfollowAccount", { params: { account } });
+  }
+
+  /** Submit a scrobble through the AppView (`app.rocksky.scrobble.createScrobble`).
+   * Auth required. For direct-to-PDS scrobbling use {@link Agent} instead. */
+  createScrobble(input: CreateScrobbleInput): Promise<ScrobbleViewBasic> {
+    return this.post("app.rocksky.scrobble.createScrobble", { body: input });
+  }
+
+  /** Create or update a mirror source (`app.rocksky.mirror.putMirrorSource`). Auth required. */
+  putMirrorSource(input: PutMirrorSourceInput): Promise<MirrorSourceView> {
+    return this.post("app.rocksky.mirror.putMirrorSource", { body: input });
+  }
+
+  /** Patch the viewer's Rockbox audio settings (`app.rocksky.rockbox.putAudioSettings`).
+   * Auth required. */
+  putAudioSettings(input: PutAudioSettingsInput): Promise<RockboxSettingsView> {
+    return this.post("app.rocksky.rockbox.putAudioSettings", { body: input });
+  }
 }

package/src/errors.ts

@@ -1,10 +1,15 @@
-/** Error thrown when a Rocksky XRPC call returns a non-2xx `{ error, message }`. */
 export class RockskyError extends Error {
+  /** The XRPC error code (e.g. "InvalidRequest", "AuthMissing"), when the
+   * server sent one. */
   readonly kind?: string;
-  constructor(payload: unknown) {
+  /** The HTTP status of the failed response, when known. */
+  readonly status?: number;
+
+  constructor(payload: unknown, status?: number) {
     const p = payload as { error?: string; message?: string } | undefined;
     super(p?.message || p?.error || "rocksky request failed");
     this.name = "RockskyError";
     this.kind = p?.error;
+    this.status = status;
   }
 }

package/src/generated/types.ts

@@ -126,6 +126,18 @@ export interface AddItemsToQueueParams {
   shuffle?: boolean;
 }
 
+export interface AddSongsOutput {
+  /** AT-URIs of the created app.rocksky.playlist.song records */
+  uris: AtUri[];
+}
+
+export interface AddSongsParams {
+  /** The URI of the playlist to add the songs to */
+  uri: AtUri;
+  /** AT-URIs of the app.rocksky.song records to add */
+  songs: AtUri[];
+}
+
 export interface AlbumGetAlbumParams {
   /** The URI of the album to retrieve. */
   uri: AtUri;
@@ -755,10 +767,12 @@ export interface GetActorPlaylistsOutput {
 export interface GetActorPlaylistsParams {
   /** The DID or handle of the actor */
   did: AtIdentifier;
-  /** The maximum number of albums to return */
+  /** The maximum number of playlists to return */
   limit?: number;
   /** The offset for pagination */
   offset?: number;
+  /** RSQL filter expression, e.g. `name=="Road trip*";track.artist=="Daft Punk"`. Supports ==, !=, <, <=, >, >=, =in=, =out=, and `;`/`and`, `,`/`or` combinators, `*` wildcards in string values. Filterable fields: name, title, description, uri, spotifyLink, tidalLink, appleMusicLink, createdAt, updatedAt. The `track.title`, `track.artist`, `track.album` and `track.albumArtist` selectors match the playlist's contents, returning playlists that contain a matching track; several `track.*` terms joined with `;` must all be satisfied by the same track. */
+  filter?: string;
 }
 
 export interface GetActorScrobblesOutput {
@@ -1565,6 +1579,23 @@ export interface LibrarySearchParams {
   songOffset?: number;
 }
 
+export interface LibraryUpdatePlaylistInput {
+  /** The playlist id to update. */
+  playlistId: string;
+  /** New playlist name. */
+  name?: string;
+  /** New playlist comment. */
+  comment?: string;
+  /** A song id to add to the playlist. */
+  songIdToAdd?: string;
+  /** A track index to remove from the playlist. */
+  songIndexToRemove?: number;
+}
+
+export interface LibraryUpdatePlaylistOutput {
+
+}
+
 export interface LikeRecord {
   /** The date when the like was created. */
   createdAt: DateTime;
@@ -1723,16 +1754,27 @@ export interface PlayFileParams {
   fileId: string;
 }
 
+export interface PlaylistCreatePlaylistOutput {
+  /** The AT-URI of the created app.rocksky.playlist record. */
+  uri: AtUri;
+  /** The CID of the created app.rocksky.playlist record. */
+  cid: string;
+}
+
 export interface PlaylistCreatePlaylistParams {
   /** The name of the playlist */
   name: string;
   /** A brief description of the playlist */
   description?: string;
+  /** The URL of the cover image for the playlist */
+  pictureUrl?: Uri;
 }
 
 export interface PlaylistGetPlaylistParams {
   /** The URI of the playlist to retrieve. */
   uri: AtUri;
+  /** RSQL filter expression applied to the playlist's tracks, 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, addedAt */
+  filter?: string;
 }
 
 export interface PlaylistGetPlaylistsOutput {
@@ -1744,15 +1786,8 @@ export interface PlaylistGetPlaylistsParams {
   limit?: number;
   /** The offset for pagination, used to skip a number of playlists. */
   offset?: number;
-}
-
-export interface PlaylistItemRecord {
-  subject: StrongRef;
-  /** The date the playlist was created. */
-  createdAt: DateTime;
-  track: SongViewBasic;
-  /** The order of the item in the playlist. */
-  order: number;
+  /** RSQL filter expression, e.g. `name=="Road trip*";track.artist=="Daft Punk"`. Supports ==, !=, <, <=, >, >=, =in=, =out=, and `;`/`and`, `,`/`or` combinators, `*` wildcards in string values. Filterable fields: name, title, description, uri, spotifyLink, tidalLink, appleMusicLink, createdAt, updatedAt, curatorDid, curatorHandle, curatorName. The `track.title`, `track.artist`, `track.album` and `track.albumArtist` selectors match the playlist's contents, returning playlists that contain a matching track; several `track.*` terms joined with `;` must all be satisfied by the same track. */
+  filter?: string;
 }
 
 export interface PlaylistRecord {
@@ -1776,6 +1811,45 @@ export interface PlaylistRecord {
   appleMusicLink?: string;
 }
 
+export interface PlaylistSongRecord {
+  /** Strong reference (AT-URI + CID) to the parent app.rocksky.playlist record. */
+  playlist: StrongRef;
+  /** Strong reference (AT-URI + CID) to the app.rocksky.song record this entry points at. */
+  song: StrongRef;
+  /** The title of the song. */
+  title: string;
+  /** The artist of the song. */
+  artist: string;
+  /** The album the song belongs to. */
+  album: string;
+  /** The album artist of the song. */
+  albumArtist: string;
+  /** The duration of the song in milliseconds. */
+  duration: number;
+  /** The URL of the album art of the song. */
+  albumArtUrl?: Uri;
+  /** The date and time the song was added to the playlist. */
+  addedAt: DateTime;
+}
+
+export interface PlaylistUpdatePlaylistOutput {
+  /** The AT-URI of the updated app.rocksky.playlist record. */
+  uri: AtUri;
+  /** The CID of the updated app.rocksky.playlist record. */
+  cid: string;
+}
+
+export interface PlaylistUpdatePlaylistParams {
+  /** The URI of the playlist to update */
+  uri: AtUri;
+  /** The new name of the playlist */
+  name?: string;
+  /** The new description of the playlist */
+  description?: string;
+  /** The new cover image URL for the playlist */
+  pictureUrl?: Uri;
+}
+
 /** Basic view of a playlist, including its metadata */
 export interface PlaylistViewBasic {
   /** The unique identifier of the playlist. */
@@ -1800,6 +1874,8 @@ export interface PlaylistViewBasic {
   createdAt?: DateTime;
   /** The number of tracks in the playlist. */
   trackCount?: number;
+  /** Album-art URLs of up to four of the playlist's tracks, for rendering a cover mosaic when the playlist has no picture of its own. */
+  trackArts?: Uri[];
 }
 
 /** Detailed view of a playlist, including its tracks and metadata */
@@ -1929,8 +2005,8 @@ export interface RemoveShoutParams {
 export interface RemoveTrackParams {
   /** The URI of the playlist to remove the track from */
   uri: AtUri;
-  /** The position of the track to remove in the playlist */
-  position: number;
+  /** The URI of the app.rocksky.song record to remove from the playlist */
+  songUri: AtUri;
 }
 
 export interface ReplyShoutInput {
@@ -2714,23 +2790,6 @@ export interface UpdateNowPlayingOutput {
 
 }
 
-export interface UpdatePlaylistInput {
-  /** The playlist id to update. */
-  playlistId: string;
-  /** New playlist name. */
-  name?: string;
-  /** New playlist comment. */
-  comment?: string;
-  /** A song id to add to the playlist. */
-  songIdToAdd?: string;
-  /** A track index to remove from the playlist. */
-  songIndexToRemove?: number;
-}
-
-export interface UpdatePlaylistOutput {
-
-}
-
 export interface UpdateSeenInput {
   /** The ids of the notifications to mark as viewed. Omit to mark all. */
   ids?: string[];
@@ -2835,7 +2894,7 @@ export interface Endpoints {
   "app.rocksky.library.startScan": StartScanOutput;
   "app.rocksky.library.unstar": UnstarOutput;
   "app.rocksky.library.updateNowPlaying": UpdateNowPlayingOutput;
-  "app.rocksky.library.updatePlaylist": UpdatePlaylistOutput;
+  "app.rocksky.library.updatePlaylist": LibraryUpdatePlaylistOutput;
   "app.rocksky.like.dislikeShout": ShoutView;
   "app.rocksky.like.dislikeSong": SongViewDetailed;
   "app.rocksky.like.likeShout": ShoutView;
@@ -2856,7 +2915,8 @@ export interface Endpoints {
   "app.rocksky.player.playFile": void;
   "app.rocksky.player.previous": void;
   "app.rocksky.player.seek": void;
-  "app.rocksky.playlist.createPlaylist": void;
+  "app.rocksky.playlist.addSongs": AddSongsOutput;
+  "app.rocksky.playlist.createPlaylist": PlaylistCreatePlaylistOutput;
   "app.rocksky.playlist.getPlaylist": PlaylistViewDetailed;
   "app.rocksky.playlist.getPlaylists": PlaylistGetPlaylistsOutput;
   "app.rocksky.playlist.insertDirectory": void;
@@ -2864,6 +2924,7 @@ export interface Endpoints {
   "app.rocksky.playlist.removePlaylist": void;
   "app.rocksky.playlist.removeTrack": void;
   "app.rocksky.playlist.startPlaylist": void;
+  "app.rocksky.playlist.updatePlaylist": PlaylistUpdatePlaylistOutput;
   "app.rocksky.rockbox.getAudioSettings": RockboxSettingsView;
   "app.rocksky.rockbox.putAudioSettings": RockboxSettingsView;
   "app.rocksky.scrobble.createScrobble": ScrobbleViewBasic;

package/src/hash.ts

@@ -1,9 +1,11 @@
-import { createHash } from "node:crypto";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
 
 // Lowercase-hex SHA-256 of s.toLowerCase() — the lowercasing is applied to the
 // whole string (not per field), matching Rocksky's server and every other SDK.
+// Pure-JS digest (@noble/hashes) so this module stays browser-safe.
 function sha256Lower(s: string): string {
-  return createHash("sha256").update(s.toLowerCase()).digest("hex");
+  return bytesToHex(sha256(new TextEncoder().encode(s.toLowerCase())));
 }
 
 /** Identity hash of a song: sha256(lower("{title} - {artist} - {album}")). */

package/src/index.ts

@@ -10,7 +10,14 @@
  */
 export { RockskyClient, DEFAULT_APPVIEW, Interval } from "./client.js";
 export type { DateInterval } from "./client.js";
-export { RockskyLibrary } from "./library.js";
+export {
+  RockskyLibrary,
+  type LibrarySong,
+  type LibraryPlaylist,
+  type LibraryPlaylistMutation,
+  type LibraryPlaylistResponse,
+  type LibraryPlaylistsResponse,
+} from "./library.js";
 export {
   Agent,
   MAX_SAFE_WRITES_PER_HOUR,
@@ -23,7 +30,9 @@ export {
   type RateLimitOptions,
   type RateLimitState,
 } from "./agent.js";
-export { RockskyIndex, totalIndexed, type IndexStats } from "./dedup.js";
+// The dedup index (classic-level, Node-only) lives on the `@rocksky/sdk/dedup`
+// subpath so this root entry stays browser-safe.
+export type { IndexStats, RockskyIndex } from "./dedup.js";
 export { runJetstream, DEFAULT_JETSTREAM_SERVERS, type JetstreamOptions } from "./jetstream.js";
 export {
   RemotePlayer,