@rocksky/sdk 0.5.0 → 0.7.0

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/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)) {