@rocksky/sdk 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocksky/sdk",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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/agent.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from "bun:test";
+
+import { Agent } from "./agent.js";
+import type { ScrobbleInput } from "./agent.js";
+
+const DID = "did:plc:test";
+
+const C_ARTIST = "app.rocksky.artist";
+const C_ALBUM = "app.rocksky.album";
+const C_SONG = "app.rocksky.song";
+const C_SCROBBLE = "app.rocksky.scrobble";
+
+/**
+ * A fake XRPC client that captures every `createRecord` call instead of hitting
+ * a PDS. Nothing here talks to the network. Returns a fresh at:// URI per write.
+ */
+function fakeAgent(idx?: unknown): {
+  agent: Agent;
+  created: { collection: string; record: Record<string, unknown> }[];
+} {
+  const created: { collection: string; record: Record<string, unknown> }[] = [];
+  let n = 0;
+  const rpc = {
+    async post(nsid: string, opts: { input: { collection: string; record: Record<string, unknown> } }) {
+      if (nsid === "com.atproto.repo.createRecord") {
+        const { collection, record } = opts.input;
+        created.push({ collection, record });
+        return { ok: true, data: { uri: `at://${DID}/${collection}/rec${++n}` } };
+      }
+      return { ok: false, data: { error: "UnexpectedCall", message: nsid } };
+    },
+  };
+  // The constructor is private (compile-time only); bun runs the source
+  // directly, so we can instantiate with a stub client + no real session.
+  const agent = new (Agent as unknown as new (...a: unknown[]) => Agent)(rpc, DID, {}, "https://pds.test");
+  if (idx) agent.useIndex(idx as never);
+  return { agent, created };
+}
+
+/**
+ * In-memory stand-in for {@link RockskyIndex}: mirrors the exact identity
+ * semantics the Agent relies on (artist by name, album by title+artist, song by
+ * title+artist+album, scrobble by song+second), without LevelDB or a PDS.
+ */
+function memIndex() {
+  const map = new Map<string, string>();
+  const k = (...parts: (string | number)[]) => parts.join("\x00");
+  return {
+    artistUri: async (_d: string, name: string) => map.get(k("artist", name)),
+    albumUri: async (_d: string, album: string, albumArtist: string) => map.get(k("album", album, albumArtist)),
+    songUri: async (_d: string, title: string, artist: string, album: string) =>
+      map.get(k("song", title, artist, album)),
+    scrobbleUri: async (_d: string, title: string, artist: string, album: string, secs: number) =>
+      map.get(k("scrobble", title, artist, album, secs)),
+    recordArtist: async (_d: string, name: string, uri: string) => void map.set(k("artist", name), uri),
+    recordAlbum: async (_d: string, album: string, albumArtist: string, uri: string) =>
+      void map.set(k("album", album, albumArtist), uri),
+    recordSong: async (_d: string, title: string, artist: string, album: string, uri: string) =>
+      void map.set(k("song", title, artist, album), uri),
+    recordScrobble: async (_d: string, title: string, artist: string, album: string, secs: number, uri: string) =>
+      void map.set(k("scrobble", title, artist, album, secs), uri),
+  };
+}
+
+const FULL: ScrobbleInput = {
+  title: "Song A",
+  artist: "Artist A",
+  albumArtist: "Artist A",
+  album: "Album A",
+  duration: 210_000,
+  year: 2021,
+  genre: "rock",
+  spotifyLink: "https://open.spotify.com/track/xyz",
+  albumArtUrl: "https://cdn.test/art.jpg",
+  createdAt: "2024-01-01T00:00:00.000Z",
+};
+
+const cols = (created: { collection: string }[]) => created.map((c) => c.collection);
+
+describe("Agent.scrobble metadata publishing", () => {
+  test("publishes artist, album, song, then the scrobble — in that order", async () => {
+    const { agent, created } = fakeAgent(memIndex());
+    await agent.scrobble(FULL);
+    expect(cols(created)).toEqual([C_ARTIST, C_ALBUM, C_SONG, C_SCROBBLE]);
+  });
+
+  test("stamps $type on every published record", async () => {
+    const { agent, created } = fakeAgent(memIndex());
+    await agent.scrobble(FULL);
+    for (const { collection, record } of created) expect(record.$type).toBe(collection);
+  });
+
+  test("derives album (title=album, artist=albumArtist) and copies scrobble fields to song", async () => {
+    const { agent, created } = fakeAgent(memIndex());
+    await agent.scrobble(FULL);
+    const album = created.find((c) => c.collection === C_ALBUM)!.record;
+    expect(album.title).toBe("Album A");
+    expect(album.artist).toBe("Artist A");
+    expect(album.year).toBe(2021);
+    expect(album.spotifyLink).toBe("https://open.spotify.com/track/xyz");
+
+    const artist = created.find((c) => c.collection === C_ARTIST)!.record;
+    expect(artist.name).toBe("Artist A");
+
+    const song = created.find((c) => c.collection === C_SONG)!.record;
+    expect(song.title).toBe("Song A");
+    expect(song.artist).toBe("Artist A");
+    expect(song.album).toBe("Album A");
+    expect(song.duration).toBe(210_000);
+    // createdAt propagates from the scrobble to every derived record.
+    for (const { record } of created) expect(record.createdAt).toBe("2024-01-01T00:00:00.000Z");
+  });
+});
+
+describe("Agent.scrobble dedup (never republish what's already in the PDS)", () => {
+  test("a second play of the same song reuses artist/album/song, writes only the scrobble", async () => {
+    const idx = memIndex();
+    const { agent, created } = fakeAgent(idx);
+    await agent.scrobble(FULL);
+    created.length = 0; // ignore the first play's writes
+
+    await agent.scrobble({ ...FULL, createdAt: "2024-01-01T01:00:00.000Z" });
+    expect(cols(created)).toEqual([C_SCROBBLE]);
+  });
+
+  test("an exact-duplicate scrobble (same second) writes nothing and returns the existing uri", async () => {
+    const idx = memIndex();
+    const { agent, created } = fakeAgent(idx);
+    const uri1 = await agent.scrobble(FULL);
+    created.length = 0;
+
+    const uri2 = await agent.scrobble(FULL);
+    expect(uri2).toBe(uri1);
+    expect(created).toHaveLength(0);
+  });
+
+  test("without an index there is no dedup — every play republishes all four records", async () => {
+    const { agent, created } = fakeAgent();
+    await agent.scrobble(FULL);
+    await agent.scrobble(FULL);
+    expect(cols(created)).toEqual([
+      C_ARTIST,
+      C_ALBUM,
+      C_SONG,
+      C_SCROBBLE,
+      C_ARTIST,
+      C_ALBUM,
+      C_SONG,
+      C_SCROBBLE,
+    ]);
+  });
+});
+
+describe("Agent.scrobble identity guards (skip records that can't be deduped)", () => {
+  test("empty album skips album + song (no stable identity), still writes artist + scrobble", async () => {
+    const { agent, created } = fakeAgent(memIndex());
+    await agent.scrobble({ title: "T", artist: "A", albumArtist: "A", album: "", duration: 0 });
+    expect(cols(created)).toEqual([C_ARTIST, C_SCROBBLE]);
+  });
+
+  test("empty albumArtist skips artist + album, still writes song + scrobble", async () => {
+    const { agent, created } = fakeAgent(memIndex());
+    await agent.scrobble({ title: "T", artist: "A", albumArtist: "", album: "Alb", duration: 0 });
+    expect(cols(created)).toEqual([C_SONG, C_SCROBBLE]);
+  });
+});

package/src/agent.ts

@@ -150,9 +150,18 @@ export class Agent {
     if (!res.ok) throw new RockskyError(res.data);
   }
 
-  /** Scrobble a play (app.rocksky.scrobble). createdAt defaults to now. */
+  /**
+   * Scrobble a play (app.rocksky.scrobble). Before writing the scrobble, this
+   * publishes the canonical metadata it implies — artist, then album, then song
+   * (in that dependency order) — so the play is self-contained in the user's
+   * PDS. Every write is deduplicated against the attached index: anything
+   * already present in the repo is skipped, never republished. createdAt
+   * defaults to now.
+   */
   async scrobble(rec: ScrobbleInput): Promise<string> {
     const record = { ...rec, createdAt: rec.createdAt || nowISO() };
+    // Materialize artist -> album -> song first (deduped). Then the scrobble.
+    await this.publishScrobbleMetadata(record);
     if (this.idx) {
       const secs = Math.floor(Date.parse(record.createdAt) / 1000);
       const existing = await this.idx.scrobbleUri(this.did, record.title!, record.artist!, record.album!, secs);
@@ -166,10 +175,46 @@ export class Agent {
     return uri;
   }
 
+  /**
+   * Publish the artist/album/song records a scrobble implies, in dependency
+   * order, each deduplicated via {@link Agent.createArtist}/`createAlbum`/
+   * `createSong`. A record is written only when its identity fields are
+   * present — artist needs an album artist, album needs title + artist, song
+   * needs title + artist + album — because a record without a stable identity
+   * hash cannot be deduped and would be republished on every scrobble.
+   */
+  private async publishScrobbleMetadata(record: ScrobbleInput & { createdAt: string }): Promise<void> {
+    const { albumArtist, album, title, artist, createdAt } = record;
+    if (albumArtist) {
+      await this.createArtist({ name: albumArtist, createdAt });
+    }
+    if (albumArtist && album) {
+      await this.createAlbum({
+        title: album,
+        artist: albumArtist,
+        releaseDate: record.releaseDate,
+        year: record.year,
+        genre: record.genre,
+        albumArtUrl: record.albumArtUrl,
+        tags: record.tags,
+        youtubeLink: record.youtubeLink,
+        spotifyLink: record.spotifyLink,
+        tidalLink: record.tidalLink,
+        appleMusicLink: record.appleMusicLink,
+        createdAt,
+      });
+    }
+    if (title && artist && album) {
+      // A song record shares the scrobble's shape verbatim.
+      await this.createSong({ ...record });
+    }
+  }
+
   /** Scrobble from just a title + artist (album optional, plus optional
    * `mbId`/`isrc` anchors): resolve full metadata via `matchSong`, then write.
    * Matching uses the public AppView unless `appview` is given; an empty match
-   * falls back to a minimal record. */
+   * falls back to a minimal record. Delegates to {@link Agent.scrobble}, so it
+   * publishes the implied artist/album/song (deduped) before the scrobble. */
   async scrobbleMatch(input: ScrobbleMatchInput, appview?: string): Promise<string> {
     const { title, artist, album, mbId, isrc, timestamp } = input;
     const { RockskyClient } = await import("./client.js");

package/src/client.ts

@@ -1,6 +1,7 @@
 import { Client, simpleFetchHandler } from "@atcute/client";
 
 import { RockskyError } from "./errors.js";
+import { RockskyLibrary } from "./library.js";
 import type {
   ActorProfileViewBasic,
   ActorProfileViewDetailed,
@@ -58,14 +59,16 @@ export const DEFAULT_APPVIEW = "https://api.rocksky.app";
 /** Unauthenticated read client over the public Rocksky AppView XRPC. */
 export class RockskyClient {
   private rpc: Client;
+  private token?: string;
 
   /**
    * Build a read client against an AppView base URL (defaults to
    * {@link DEFAULT_APPVIEW}). Pass `token` to send it as
    * `Authorization: Bearer <token>` on every read — needed only for auth-gated
-   * queries.
+   * queries and the whole {@link RockskyClient.library} surface.
    */
   constructor(appview: string = DEFAULT_APPVIEW, token?: string) {
+    this.token = token;
     let handler = simpleFetchHandler({ service: appview });
     if (token) {
       const inner = handler;
@@ -78,6 +81,20 @@ export class RockskyClient {
     this.rpc = new Client({ handler });
   }
 
+  /**
+   * The authenticated `app.rocksky.library.*` (uploaded-music) API. Every
+   * library method requires auth, so this throws unless the client was built
+   * with a token.
+   */
+  library(): RockskyLibrary {
+    if (!this.token) {
+      throw new Error(
+        "app.rocksky.library.* requires an access token; construct RockskyClient(appview, token) first",
+      );
+    }
+    return new RockskyLibrary(this.rpc);
+  }
+
   private async query<T>(nsid: string, params: Record<string, unknown>): Promise<T> {
     const clean: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(params)) {