@rocksky/sdk 0.3.0 → 0.5.0

package/README.md

@@ -1,284 +1,110 @@
 # @rocksky/sdk
 
-A TypeScript SDK for the [Rocksky](https://rocksky.app) XRPC API.
-
-- **Type-safe** — every endpoint and parameter is statically typed.
-- **Builder-friendly** — fluent `RockskyClient.builder()` for ergonomic setup.
-- **Pipe-friendly** — composable async operators (`pipe`, `withRetry`, `withTimeout`, `map`, `tap`, `withFallback`, `catchError`).
-- **Zero-dependency** — only uses the platform `fetch` and the standard library. Works on Bun, Node 18+, Deno, browsers, Cloudflare Workers.
+Official TypeScript SDK for [Rocksky](https://rocksky.app) — a music scrobbling &
+discovery platform on the AT Protocol. Built on
+[atcute](https://github.com/mary-ext/atcute): `RockskyClient` does unauthenticated
+AppView reads, and `Agent` logs in with an app password and writes
+`app.rocksky.*` records to the user's PDS.
 
 ## Install
 
-```bash
-bun add @rocksky/sdk
-# or
-npm i @rocksky/sdk
-```
-
-## Quick start
-
-```ts
-import { createClient } from "@rocksky/sdk";
-
-const client = createClient();
-
-const profile = await client.actor.getProfile({ did: "did:plc:7vdlgi2bflelz7mmuxoqjfcr" });
-const topTracks = await client.charts.getTopTracks({ limit: 5 });
+```sh
+npm install @rocksky/sdk      # or: bun add @rocksky/sdk
 ```
 
-## Authentication
-
-The SDK accepts a bearer token either as a string or as a (sync/async) function:
+## Quickstart
 
 ```ts
-import { createClient } from "@rocksky/sdk";
-
-const client = createClient({ auth: process.env.ROCKSKY_TOKEN });
-
-// or — refresh on every call
-const client = createClient({
-  auth: async () => loadTokenFromKeychain(),
+import { RockskyClient, Agent } from "@rocksky/sdk";
+
+// Reads — unauthenticated. new RockskyClient() uses https://api.rocksky.app.
+const rk = new RockskyClient();
+const stats = await rk.globalStats();
+const top = await rk.topTracks(10, 0);
+
+// Writes — log in with an app password (resolves the PDS automatically).
+const agent = await Agent.login("alice.bsky.social", "app-password");
+const uri = await agent.scrobble({
+  title: "Chaser", artist: "Calibro 35",
+  album: "Jazzploitation", albumArtist: "Calibro 35", duration: 182320,
 });
 ```
 
-Endpoints that require auth throw `RockskyAuthError` when no token is configured.
-
-## Builder
+## API
 
-```ts
-import { RockskyClient } from "@rocksky/sdk";
-
-const client = RockskyClient.builder()
-  .baseUrl("https://api.rocksky.app")
-  .bearer(process.env.ROCKSKY_TOKEN!)
-  .userAgent("my-app/1.0")
-  .timeout(10_000)
-  .retries(3)
-  .retryDelay(200)
-  .header("x-trace-id", crypto.randomUUID())
-  .build();
-```
+**Reads — `RockskyClient`**: the client now covers the whole `app.rocksky.*`
+read surface. Typed methods include `profile`, `scrobbles`, `songs`, `albums`,
+`artists`, `topTracks`, `topArtists`, `search`, `globalStats`, `lovedSongs`,
+`catalogAlbums`, `catalogArtists`, `catalogSongs`, `albumTracks`, `artistAlbums`,
+`artistTracks`, `scrobbleFeed`, `scrobble` (single by uri), `follows`,
+`followers`, `knownFollowers`. Raw (`unknown`-returning) detail/long-tail
+methods cover the rest: `album`, `artist`, `song`, `feed`, `playlists`,
+`playlist`, `stats`, `wrapped`, `scrobblesChart`, `recommendations`,
+`neighbours`, shouts, and more.
 
-`withAuth(token)` and `withBaseUrl(url)` return a new client without mutating the original — handy for per-request overrides.
+Every named method is sugar over the universal escape hatch **`rk.get(nsid,
+params)`**, which calls ANY read query by nsid and returns `unknown`.
 
-## Pipe-style composition
+**Typed date-window charts**: `topTracksInterval(limit, offset, interval)` and
+`topArtistsInterval(...)` take a `DateInterval` built with the `Interval`
+factories — `Interval.allTime()`, `Interval.lastDays(n)`, `Interval.lastWeeks(n)`,
+`Interval.lastMonths(n)`, `Interval.lastYears(n)`, `Interval.range(start, end)`.
+`topTracks` / `topArtists` remain all-time shorthands.
 
 ```ts
-import {
-  createClient,
-  map,
-  pipe,
-  tap,
-  withFallback,
-  withRetry,
-  withTimeout,
-} from "@rocksky/sdk";
+import { RockskyClient, Interval } from "@rocksky/sdk";
 
-const client = createClient();
+const rk = new RockskyClient();
+const monthly = await rk.topTracksInterval(10, 0, Interval.lastMonths(1));
 
-// Pass a thunk so withRetry can re-invoke the network call.
-const handle = await pipe(
-  () => client.actor.getProfile({ did: "did:plc:7vdlgi2bflelz7mmuxoqjfcr" }),
-  withRetry(3, { delayMs: 200 }),
-  withTimeout(5_000),
-  tap((p) => console.log("loaded", p.handle)),
-  map((p) => p.displayName ?? p.handle),
-  withFallback("anonymous"),
-);
+// Resolve a bare title + artist into full canonical metadata.
+const song = await rk.matchSong("Chaser", "Calibro 35");
 ```
 
-`pipe` accepts either a thunk `() => Promise<T>` (preferred — `withRetry` re-runs it) or a bare `Promise<T>` for one-shot composition.
+**`matchSong(title, artist, mbId?, isrc?)`**: resolves a bare title + artist into
+full canonical metadata (album, artwork, duration, MBID, ISRC, links).
 
-| Operator | Description |
-| --- | --- |
-| `map(fn)` | Transform the resolved value. |
-| `tap(fn)` | Run a side-effect; pass the value through. |
-| `withRetry(n, { delayMs, factor, shouldRetry })` | Retry on rejection with exponential backoff. |
-| `withTimeout(ms)` | Reject with `RockskyTimeoutError` if it exceeds `ms`. |
-| `withFallback(value \| fn)` | Recover from any error with a default. |
-| `catchError(fn)` | Map a thrown error to a value. |
+**Auth-gated reads**: pass an optional bearer access token —
+`new RockskyClient(appview, token)` — and it is sent as
+`Authorization: Bearer <token>`.
 
-## Namespaces
+**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
+`createSong`/`createAlbum`/`createArtist`, `like`, `follow`,
+`shout`/`replyShout`, `setNowPlaying`/`clearNowPlaying`, `delete`. Records are the
+generated types from `./generated/types`.
 
-```
-client.actor        getProfile, getActorAlbums, getActorArtists, getActorSongs,
-                    getActorScrobbles, getActorLovedSongs, getActorPlaylists,
-                    getActorNeighbours, getActorCompatibility
-client.album        getAlbum, getAlbums, getAlbumTracks
-client.apikey       getApikeys, createApikey, updateApikey, removeApikey
-client.artist       getArtist, getArtists, getArtistAlbums, getArtistTracks,
-                    getArtistListeners, getArtistRecentListeners
-client.charts       getScrobblesChart, getTopArtists, getTopTracks
-client.dropbox      getFiles, getMetadata, getTemporaryLink, downloadFile
-client.feed         search, getFeed, getFeedGenerators, getFeedGenerator,
-                    describeFeedGenerator, getFeedSkeleton,
-                    getRecommendations, getArtistRecommendations,
-                    getAlbumRecommendations, getStories
-client.googledrive  getFile, getFiles, downloadFile
-client.graph        followAccount, unfollowAccount, getFollowers, getFollows,
-                    getKnownFollowers
-client.like         likeSong, dislikeSong, likeShout, dislikeShout
-client.mirror       getMirrorSources, putMirrorSource
-client.player       getCurrentlyPlaying, getPlaybackQueue, play, pause, next,
-                    previous, seek, playFile, playDirectory, addItemsToQueue,
-                    addDirectoryToQueue
-client.playlist     getPlaylists, getPlaylist, createPlaylist, removePlaylist,
-                    startPlaylist, insertDirectory, insertFiles, removeTrack
-client.scrobble     createScrobble, getScrobble, getScrobbles
-client.shout        createShout, replyShout, reportShout, removeShout,
-                    getShoutReplies, getProfileShouts, getTrackShouts,
-                    getArtistShouts, getAlbumShouts
-client.song         getSong, getSongs, getSongRecentListeners, matchSong,
-                    createSong
-client.spotify      getCurrentlyPlaying, play, pause, next, previous, seek
-client.stats        getStats, getWrapped
-```
+**Identity hashes**: `songHash`, `albumHash`, `artistHash` — lowercase-hex
+SHA-256, identical to the server and every other Rocksky SDK.
 
-Every method takes a typed parameter object and returns `Promise<T>`. Pass a generic to narrow the response type:
+## Duplicate prevention + real-time sync
 
-```ts
-type Profile = { handle: string; did: string; displayName?: string };
-const me = await client.actor.getProfile<Profile>({ did: "alice.bsky.social" });
-```
-
-## Escape hatch
-
-For endpoints not yet wrapped, call `xrpc` directly:
+An optional local index (embedded [classic-level](https://github.com/Level/classic-level)
+LevelDB) prevents duplicate writes and stays live off the firehose:
 
 ```ts
-const result = await client.xrpc<MyType>(
-  "app.rocksky.something.notWrappedYet",
-  "GET",
-  { params: { foo: "bar" } },
-);
-```
+import { RockskyIndex } from "@rocksky/sdk";
 
-## Error handling
+const idx = new RockskyIndex("./dedup");
+await idx.open();
+agent.useIndex(idx);
 
-The SDK throws four error classes — all extending `RockskyError`:
-
-- `RockskyHttpError` — non-2xx response. Exposes `.status`, `.statusText`, `.url`, `.body`.
-- `RockskyTimeoutError` — request exceeded `timeoutMs`.
-- `RockskyAuthError` — endpoint requires auth but no token was provided.
-- `RockskyError` — base class.
-
-```ts
-import { RockskyHttpError } from "@rocksky/sdk";
-
-try {
-  await client.scrobble.getScrobble({ uri: "at://x" });
-} catch (err) {
-  if (err instanceof RockskyHttpError && err.status === 404) {
-    console.log("not found");
-  } else {
-    throw err;
-  }
-}
+const stats = await agent.syncRepo();     // backfill from the repo CAR (com.atproto.sync.getRepo)
+agent.hydrateFromJetstream();             // keep it live from Jetstream (all 4 servers)
 ```
 
-## Pagination
-
-`paginate()` (and `client.paginate()`) gives you a typed async iterable over any `{ limit, offset }` or `{ cursor }` endpoint.
+With an index attached, the write verbs skip records that already exist (return
+the existing URI) and a same-second scrobble of the same track isn't duplicated.
 
-```ts
-import { createClient, paginate } from "@rocksky/sdk";
-
-const client = createClient();
-
-// Offset/limit — fetcher returns the items array, helper handles offset.
-for await (const s of paginate({
-  fetch: ({ limit, offset }) =>
-    client.actor.getActorScrobbles({ did, limit, offset }).then((p) => p.scrobbles ?? []),
-  pageSize: 50,
-  maxItems: 200,
-})) {
-  console.log(s.track.title);
-}
-
-// Cursor-based — fetcher returns { items, cursor }.
-const followers = await client
-  .paginate({
-    fetch: async ({ limit, cursor }) => {
-      const page = await client.graph.getFollowers({ actor, limit, cursor });
-      return { items: page.followers, cursor: page.cursor };
-    },
-    pageSize: 100,
-  })
-  .toArray();
-```
-
-Options: `pageSize`, `maxItems`, `signal` (AbortSignal). The helper stops on an empty page, a short page (offset mode), or a missing cursor (cursor mode).
-
-## Realtime (WebSocket)
-
-The Rocksky API exposes a WebSocket endpoint at `/ws` for now-playing events and device control. The SDK ships a typed client with reconnect, ping, and a fluent builder.
-
-```ts
-import { RealtimeClient, createClient } from "@rocksky/sdk";
-
-// Builder style.
-const rt = RealtimeClient.builder()
-  .baseUrl("https://api.rocksky.app")
-  .token(process.env.ROCKSKY_TOKEN!)
-  .clientName("my-app")
-  .pingInterval(20_000)
-  .reconnect({ backoffMs: 1000, maxBackoffMs: 60_000 })
-  .build();
-
-// Or — inherit baseUrl from a RockskyClient.
-const client = createClient({ baseUrl: "https://api.rocksky.app" });
-const rt2 = client.realtime({ token: process.env.ROCKSKY_TOKEN!, clientName: "my-app" });
-
-rt.on("open", () => console.log("connected"));
-rt.on("registered", ({ deviceId }) => console.log("device id:", deviceId));
-rt.on("message", ({ data, device_id }) => console.log(device_id, data));
-rt.on("control", (c) => console.log("control:", c));
-rt.on("close", ({ code, reason }) => console.log("closed", code, reason));
-rt.on("error", (err) => console.error(err));
-
-await rt.connect();
-
-// Broadcast a now-playing update to your devices.
-await rt.sendMessage({
-  type: "track",
-  title: "Heart of Glass",
-  artist: "Blondie",
-});
-
-// Control a target device (or all of them).
-await rt.sendControl({ action: "play", target: "device-id-123" });
-
-await rt.close();
-```
-
-Events: `open`, `close`, `error`, `registered`, `deviceRegistered`, `message`, `control`, `raw`.
-
-For tests, pass a fake `WebSocket` constructor via `.webSocket(FakeWebSocket)`.
-
-## Types
-
-Public model types are derived from the [Rocksky lexicons](https://tangled.org/rocksky.app/rocksky/tree/main/apps/api/lexicons) and live in `src/generated/types.ts`. They are regenerated from `apps/api/lexicons/**/*.json` by running `bun run lexgen:types` at the repo root.
-
-
-## Development
-
-```bash
-bun install
-bun test
-bun run typecheck
-bun run build
-```
+Node ≥ 22 (global `WebSocket`/`fetch`) or Bun.
 
-Run individual examples:
+## Example
 
-```bash
-bun run example:quickstart
-bun run example:builder
-bun run example:pipe
-bun run example:scrobble
-bun run example:pagination
+```sh
+bun run examples/native.ts
 ```
 
 ## License
 
-[MIT](LICENSE) © Tsiry Sandratraina.
+MIT.

package/dist/agent.d.ts

@@ -0,0 +1,82 @@
+import { PasswordSession } from "@atcute/password-session";
+import type { AlbumRecord, ArtistRecord, ActorTrackView, ScrobbleRecord, SongRecord } from "./generated/types.js";
+import type { IndexStats, RockskyIndex } from "./dedup.js";
+import { type JetstreamOptions } from "./jetstream.js";
+/** Input for {@link Agent.scrobble} (createdAt defaults to now). */
+export type ScrobbleInput = Omit<ScrobbleRecord, "createdAt"> & {
+    createdAt?: string;
+};
+/** Input for {@link Agent.createSong}. */
+export type SongInput = Omit<SongRecord, "createdAt"> & {
+    createdAt?: string;
+};
+/** Input for {@link Agent.createAlbum} (`artist` is the album artist). */
+export type AlbumInput = Omit<AlbumRecord, "createdAt"> & {
+    createdAt?: string;
+};
+/** Input for {@link Agent.createArtist}. */
+export type ArtistInput = Omit<ArtistRecord, "createdAt"> & {
+    createdAt?: string;
+};
+/**
+ * Authenticated Rocksky client: logs in with an app password and writes
+ * app.rocksky.* records to the user's PDS (via atcute). Attach a
+ * {@link RockskyIndex} with {@link Agent.useIndex} for duplicate prevention.
+ */
+export declare class Agent {
+    private rpc;
+    readonly did: string;
+    readonly session: PasswordSession;
+    private pds;
+    private idx?;
+    private constructor();
+    /**
+     * Resolve the account's PDS, authenticate with an app password, and return an
+     * Agent. `identifier` is a handle or DID.
+     */
+    static login(identifier: string, password: string): Promise<Agent>;
+    /** Attach a local dedup index — write verbs then skip records that already exist. */
+    useIndex(idx: RockskyIndex): void;
+    /**
+     * Download the caller's full repository and (re)build the dedup index. Requires
+     * an attached index ({@link Agent.useIndex}). Full backfill; keep it current
+     * with {@link Agent.hydrateFromJetstream}.
+     */
+    syncRepo(): Promise<IndexStats>;
+    /**
+     * Keep the dedup index live from the Bluesky Jetstream firehose (all four
+     * servers at once, filtered to this DID + app.rocksky.*). Resolves when the
+     * options' AbortSignal fires. Requires an attached index.
+     */
+    hydrateFromJetstream(opts?: JetstreamOptions): Promise<void>;
+    private create;
+    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(rec: ScrobbleInput): Promise<string>;
+    /** 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. */
+    scrobbleMatch(title: string, artist: string, album?: string, mbId?: string, isrc?: string, 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. */
+    createAlbum(rec: AlbumInput): Promise<string>;
+    /** Create an artist record (app.rocksky.artist). */
+    createArtist(rec: ArtistInput): Promise<string>;
+    /** Like a record by strong reference (uri + cid). Returns the like URI. */
+    like(uri: string, cid: string): Promise<string>;
+    /** Follow an account by DID. Returns the follow URI. */
+    follow(did: string): Promise<string>;
+    /** Post a shout on a subject. Returns the shout URI. */
+    shout(subjectUri: string, subjectCid: string, message: string): Promise<string>;
+    /** Reply to a shout, with a parent strong-ref. */
+    replyShout(subjectUri: string, subjectCid: string, parentUri: string, parentCid: string, message: string): Promise<string>;
+    /** Upsert the actor's now-playing status singleton (rkey "self"). */
+    setNowPlaying(track: ActorTrackView): Promise<string>;
+    /** Delete the actor's now-playing status singleton. */
+    clearNowPlaying(): Promise<void>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}