@rocksky/sdk 0.7.0 → 0.7.1

package/dist/agent.d.ts

@@ -66,12 +66,29 @@ export declare class Agent {
     private putRecord;
     /** Delete a record by collection + rkey. */
     delete(collection: string, rkey: string): Promise<void>;
-    /** 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.
+     */
     scrobble(rec: ScrobbleInput): Promise<string>;
+    /**
+     * 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 publishScrobbleMetadata;
     /** 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. */
     scrobbleMatch(input: ScrobbleMatchInput, appview?: string): Promise<string>;
     /** Create a canonical track record (app.rocksky.song). */
     createSong(rec: SongInput): Promise<string>;

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAG3D,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,cAAc,EACd,UAAU,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AA+BrE,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACvF,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/E,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACjF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;;GAIG;AACH,qBAAa,KAAK;IAId,OAAO,CAAC,GAAG;IACX,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,OAAO,EAAE,eAAe;IACjC,OAAO,CAAC,GAAG;IANb,OAAO,CAAC,GAAG,CAAC,CAAe;IAE3B,OAAO;IAOP;;;OAGG;WACU,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAMxE,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAIjC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IASrC;;;;OAIG;IACH,oBAAoB,CAAC,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;YAKlD,MAAM;YAQN,SAAS;IAQvB,4CAA4C;IACtC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7D;;;;;;;OAOG;IACG,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBnD;;;;;;;OAOG;YACW,uBAAuB;IA2BrC;;;;gFAI4E;IACtE,aAAa,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsCjF,0DAA0D;IACpD,UAAU,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAWjD,gFAAgF;IAC1E,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAWnD,oDAAoD;IAC9C,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAWrD,2EAA2E;IAC3E,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C,wDAAwD;IACxD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpC,wDAAwD;IACxD,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/E,kDAAkD;IAClD,UAAU,CACR,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC;IASlB,qEAAqE;IACrE,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD,uDAAuD;IACvD,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC"}

package/dist/agent.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent.test.d.ts.map

package/dist/agent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.test.d.ts","sourceRoot":"","sources":["../src/agent.test.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -6160,6 +6160,7 @@ class Agent {
   }
   async scrobble(rec) {
     const record2 = { ...rec, createdAt: rec.createdAt || nowISO() };
+    await this.publishScrobbleMetadata(record2);
     if (this.idx) {
       const secs = Math.floor(Date.parse(record2.createdAt) / 1000);
       const existing = await this.idx.scrobbleUri(this.did, record2.title, record2.artist, record2.album, secs);
@@ -6173,6 +6174,31 @@ class Agent {
     }
     return uri2;
   }
+  async publishScrobbleMetadata(record2) {
+    const { albumArtist, album, title, artist, createdAt } = record2;
+    if (albumArtist) {
+      await this.createArtist({ name: albumArtist, createdAt });
+    }
+    if (albumArtist && album) {
+      await this.createAlbum({
+        title: album,
+        artist: albumArtist,
+        releaseDate: record2.releaseDate,
+        year: record2.year,
+        genre: record2.genre,
+        albumArtUrl: record2.albumArtUrl,
+        tags: record2.tags,
+        youtubeLink: record2.youtubeLink,
+        spotifyLink: record2.spotifyLink,
+        tidalLink: record2.tidalLink,
+        appleMusicLink: record2.appleMusicLink,
+        createdAt
+      });
+    }
+    if (title && artist && album) {
+      await this.createSong({ ...record2 });
+    }
+  }
   async scrobbleMatch(input, appview) {
     const { title, artist, album, mbId, isrc, timestamp } = input;
     const { RockskyClient: RockskyClient2 } = await Promise.resolve().then(() => (init_client2(), exports_client));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocksky/sdk",
-  "version": "0.7.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");