@rocksky/sdk 0.5.0 → 0.6.0

package/README.md

@@ -69,8 +69,13 @@ full canonical metadata (album, artwork, duration, MBID, ISRC, links).
 `Authorization: Bearer <token>`.
 
 **Writes — `Agent`**: two scrobble paths. `scrobble(rec)` writes full metadata
-you already have; `scrobbleMatch(title, artist, album?, mbId?, isrc?)` resolves
-full metadata via `matchSong` first, then writes. Plus
+you already have; `scrobbleMatch(input, appview?)` takes a `ScrobbleMatchInput`
+object (`{ title, artist, album?, mbId?, isrc?, timestamp? }` — title/artist
+required; `album` overrides the resolved album, `mbId`/`isrc` are match anchors,
+`timestamp` is a scrobbled-at Unix-seconds time; the optional `appview` overrides
+the AppView used for matching) and resolves full metadata via `matchSong` first,
+then writes — e.g. `agent.scrobbleMatch({ title: "Chaser", artist: "Calibro 35" })`.
+Plus
 `createSong`/`createAlbum`/`createArtist`, `like`, `follow`,
 `shout`/`replyShout`, `setNowPlaying`/`clearNowPlaying`, `delete`. Records are the
 generated types from `./generated/types`.

package/dist/agent.d.ts

@@ -6,6 +6,19 @@ import { type JetstreamOptions } from "./jetstream.js";
 export type ScrobbleInput = Omit<ScrobbleRecord, "createdAt"> & {
     createdAt?: string;
 };
+/** Input for {@link Agent.scrobbleMatch} — `title`/`artist` required, rest optional. */
+export interface ScrobbleMatchInput {
+    title: string;
+    artist: string;
+    /** Overrides the matched album. */
+    album?: string;
+    /** MusicBrainz recording id — anchors the match. */
+    mbId?: string;
+    /** ISRC — anchors the match. */
+    isrc?: string;
+    /** Scrobbled-at Unix seconds; omitted = now. */
+    timestamp?: number;
+}
 /** Input for {@link Agent.createSong}. */
 export type SongInput = Omit<SongRecord, "createdAt"> & {
     createdAt?: string;
@@ -59,7 +72,7 @@ export declare class Agent {
      * `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. */
-    scrobbleMatch(title: string, artist: string, album?: string, mbId?: string, isrc?: string, appview?: string): Promise<string>;
+    scrobbleMatch(input: ScrobbleMatchInput, appview?: string): Promise<string>;
     /** Create a canonical track record (app.rocksky.song). */
     createSong(rec: SongInput): Promise<string>;
     /** Create an album record (app.rocksky.album). `artist` is the album artist. */

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":"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"}

package/dist/index.d.ts

@@ -10,7 +10,7 @@
  */
 export { RockskyClient, DEFAULT_APPVIEW, Interval } from "./client.js";
 export type { DateInterval } from "./client.js";
-export { Agent, type ScrobbleInput, type SongInput, type AlbumInput, type ArtistInput } from "./agent.js";
+export { Agent, type ScrobbleInput, type ScrobbleMatchInput, type SongInput, type AlbumInput, type ArtistInput, } from "./agent.js";
 export { RockskyIndex, totalIndexed, type IndexStats } from "./dedup.js";
 export { runJetstream, DEFAULT_JETSTREAM_SERVERS, type JetstreamOptions } from "./jetstream.js";
 export { songHash, albumHash, artistHash } from "./hash.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC1G,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,mBAAmB,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,KAAK,EACL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,mBAAmB,sBAAsB,CAAC"}

package/dist/index.js

@@ -6007,7 +6007,8 @@ class Agent {
     }
     return uri2;
   }
-  async scrobbleMatch(title, artist, album, mbId, isrc, appview) {
+  async scrobbleMatch(input, appview) {
+    const { title, artist, album, mbId, isrc, timestamp } = input;
     const { RockskyClient: RockskyClient2 } = await Promise.resolve().then(() => (init_client2(), exports_client));
     const m = await new RockskyClient2(appview).matchSong(title, artist, mbId, isrc);
     const s = (k) => m && typeof m[k] === "string" ? m[k] : undefined;
@@ -6033,6 +6034,8 @@ class Agent {
       tidalLink: s("tidalLink"),
       appleMusicLink: s("appleMusicLink")
     } : { title, artist, album: album ?? "", albumArtist: artist, duration: 0 };
+    if (timestamp !== undefined)
+      rec.createdAt = new Date(timestamp * 1000).toISOString();
     return this.scrobble(rec);
   }
   async createSong(rec) {

package/package.json

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

@@ -52,6 +52,19 @@ function nowISO(): string {
 // Write inputs: `createdAt` is optional (the SDK defaults it to now).
 /** Input for {@link Agent.scrobble} (createdAt defaults to now). */
 export type ScrobbleInput = Omit<ScrobbleRecord, "createdAt"> & { createdAt?: string };
+/** Input for {@link Agent.scrobbleMatch} — `title`/`artist` required, rest optional. */
+export interface ScrobbleMatchInput {
+  title: string;
+  artist: string;
+  /** Overrides the matched album. */
+  album?: string;
+  /** MusicBrainz recording id — anchors the match. */
+  mbId?: string;
+  /** ISRC — anchors the match. */
+  isrc?: string;
+  /** Scrobbled-at Unix seconds; omitted = now. */
+  timestamp?: number;
+}
 /** Input for {@link Agent.createSong}. */
 export type SongInput = Omit<SongRecord, "createdAt"> & { createdAt?: string };
 /** Input for {@link Agent.createAlbum} (`artist` is the album artist). */
@@ -157,14 +170,8 @@ export class Agent {
    * `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. */
-  async scrobbleMatch(
-    title: string,
-    artist: string,
-    album?: string,
-    mbId?: string,
-    isrc?: string,
-    appview?: string,
-  ): Promise<string> {
+  async scrobbleMatch(input: ScrobbleMatchInput, appview?: string): Promise<string> {
+    const { title, artist, album, mbId, isrc, timestamp } = input;
     const { RockskyClient } = await import("./client.js");
     const m = (await new RockskyClient(appview).matchSong(title, artist, mbId, isrc)) as Record<
       string,
@@ -196,6 +203,8 @@ export class Agent {
             appleMusicLink: s("appleMusicLink"),
           }
         : { title, artist, album: album ?? "", albumArtist: artist, duration: 0 };
+    // "Scrobbled at" — Unix seconds; omitted -> scrobble() defaults to now.
+    if (timestamp !== undefined) rec.createdAt = new Date(timestamp * 1000).toISOString();
     return this.scrobble(rec);
   }
 

package/src/index.ts

@@ -10,7 +10,14 @@
  */
 export { RockskyClient, DEFAULT_APPVIEW, Interval } from "./client.js";
 export type { DateInterval } from "./client.js";
-export { Agent, type ScrobbleInput, type SongInput, type AlbumInput, type ArtistInput } from "./agent.js";
+export {
+  Agent,
+  type ScrobbleInput,
+  type ScrobbleMatchInput,
+  type SongInput,
+  type AlbumInput,
+  type ArtistInput,
+} from "./agent.js";
 export { RockskyIndex, totalIndexed, type IndexStats } from "./dedup.js";
 export { runJetstream, DEFAULT_JETSTREAM_SERVERS, type JetstreamOptions } from "./jetstream.js";
 export { songHash, albumHash, artistHash } from "./hash.js";