@rocksky/sdk 0.3.0 → 0.4.0

package/README.md

@@ -1,284 +1,74 @@
 # @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
-
-```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();
-```
-
-`withAuth(token)` and `withBaseUrl(url)` return a new client without mutating the original — handy for per-request overrides.
-
-## Pipe-style composition
-
-```ts
-import {
-  createClient,
-  map,
-  pipe,
-  tap,
-  withFallback,
-  withRetry,
-  withTimeout,
-} from "@rocksky/sdk";
-
-const client = createClient();
-
-// 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"),
-);
-```
-
-`pipe` accepts either a thunk `() => Promise<T>` (preferred — `withRetry` re-runs it) or a bare `Promise<T>` for one-shot composition.
-
-| 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. |
-
-## Namespaces
-
-```
-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
-```
-
-Every method takes a typed parameter object and returns `Promise<T>`. Pass a generic to narrow the response type:
-
-```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:
-
-```ts
-const result = await client.xrpc<MyType>(
-  "app.rocksky.something.notWrappedYet",
-  "GET",
-  { params: { foo: "bar" } },
-);
-```
-
-## Error handling
-
-The SDK throws four error classes — all extending `RockskyError`:
+## API
 
-- `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.
+**Reads — `RockskyClient`**: `profile`, `scrobbles`, `songs`, `albums`,
+`artists`, `topTracks`, `topArtists`, `search`, `globalStats`.
 
-```ts
-import { RockskyHttpError } from "@rocksky/sdk";
+**Writes — `Agent`**: `scrobble`, `createSong`/`createAlbum`/`createArtist`,
+`like`, `follow`, `shout`/`replyShout`, `setNowPlaying`/`clearNowPlaying`,
+`delete`. Records are the generated types from `./generated/types`.
 
-try {
-  await client.scrobble.getScrobble({ uri: "at://x" });
-} catch (err) {
-  if (err instanceof RockskyHttpError && err.status === 404) {
-    console.log("not found");
-  } else {
-    throw err;
-  }
-}
-```
+**Identity hashes**: `songHash`, `albumHash`, `artistHash` — lowercase-hex
+SHA-256, identical to the server and every other Rocksky SDK.
 
-## Pagination
+## Duplicate prevention + real-time sync
 
-`paginate()` (and `client.paginate()`) gives you a typed async iterable over any `{ limit, offset }` or `{ cursor }` endpoint.
+An optional local index (embedded [classic-level](https://github.com/Level/classic-level)
+LevelDB) prevents duplicate writes and stays live off the firehose:
 
 ```ts
-import { createClient, paginate } from "@rocksky/sdk";
+import { RockskyIndex } from "@rocksky/sdk";
 
-const client = createClient();
+const idx = new RockskyIndex("./dedup");
+await idx.open();
+agent.useIndex(idx);
 
-// 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();
+const stats = await agent.syncRepo();     // backfill from the repo CAR (com.atproto.sync.getRepo)
+agent.hydrateFromJetstream();             // keep it live from Jetstream (all 4 servers)
 ```
 
-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();
+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.
 
-// 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,77 @@
+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>;
+    /** 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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"}

package/dist/client.d.ts

@@ -1,116 +1,29 @@
-import { type HttpClientConfig } from "./http.js";
-import { type PaginateArgs } from "./paginate.js";
-import { RealtimeClient, type RealtimeOptions } from "./realtime.js";
-import { ActorNamespace } from "./namespaces/actor.js";
-import { AlbumNamespace } from "./namespaces/album.js";
-import { ApikeyNamespace } from "./namespaces/apikey.js";
-import { ArtistNamespace } from "./namespaces/artist.js";
-import { ChartsNamespace } from "./namespaces/charts.js";
-import { DropboxNamespace } from "./namespaces/dropbox.js";
-import { FeedNamespace } from "./namespaces/feed.js";
-import { GoogleDriveNamespace } from "./namespaces/googledrive.js";
-import { GraphNamespace } from "./namespaces/graph.js";
-import { LikeNamespace } from "./namespaces/like.js";
-import { MirrorNamespace } from "./namespaces/mirror.js";
-import { PlayerNamespace } from "./namespaces/player.js";
-import { PlaylistNamespace } from "./namespaces/playlist.js";
-import { ScrobbleNamespace } from "./namespaces/scrobble.js";
-import { ShoutNamespace } from "./namespaces/shout.js";
-import { SongNamespace } from "./namespaces/song.js";
-import { SpotifyNamespace } from "./namespaces/spotify.js";
-import { StatsNamespace } from "./namespaces/stats.js";
-import type { Endpoints } from "./generated/types.js";
-import type { AuthProvider, ClientOptions, FetchLike, RequestOptions } from "./types.js";
-type XrpcOpts = {
-    params?: Record<string, unknown>;
-    body?: unknown;
-    requireAuth?: boolean;
-} & RequestOptions;
+import type { ActorProfileViewDetailed, AlbumViewBasic, ArtistViewBasic, FeedSearchResultsView, ScrobbleViewBasic, SongViewBasic, StatsGlobalStatsView } from "./generated/types.js";
+/** The default public Rocksky AppView base URL. */
+export declare const DEFAULT_APPVIEW = "https://api.rocksky.app";
+/** Unauthenticated read client over the public Rocksky AppView XRPC. */
 export declare class RockskyClient {
-    readonly config: HttpClientConfig;
-    readonly actor: ActorNamespace;
-    readonly album: AlbumNamespace;
-    readonly apikey: ApikeyNamespace;
-    readonly artist: ArtistNamespace;
-    readonly charts: ChartsNamespace;
-    readonly dropbox: DropboxNamespace;
-    readonly feed: FeedNamespace;
-    readonly googledrive: GoogleDriveNamespace;
-    readonly graph: GraphNamespace;
-    readonly like: LikeNamespace;
-    readonly mirror: MirrorNamespace;
-    readonly player: PlayerNamespace;
-    readonly playlist: PlaylistNamespace;
-    readonly scrobble: ScrobbleNamespace;
-    readonly shout: ShoutNamespace;
-    readonly song: SongNamespace;
-    readonly spotify: SpotifyNamespace;
-    readonly stats: StatsNamespace;
-    constructor(options?: ClientOptions);
-    /** Build a one-off authenticated copy without mutating this client. */
-    withAuth(auth: AuthProvider): RockskyClient;
-    /** Build a copy with an overridden base URL. */
-    withBaseUrl(baseUrl: string): RockskyClient;
-    /**
-     * Open a realtime WebSocket connection to /ws.
-     *
-     *   const rt = client.realtime({ token, clientName: "my-app" });
-     *   rt.on("message", m => console.log(m));
-     *   await rt.connect();
-     *
-     * Defaults `baseUrl` to this client's base URL. Override anything by
-     * passing the option, or use `RealtimeClient.builder()` for full control.
-     */
-    realtime(options: Omit<RealtimeOptions, "baseUrl"> & Partial<Pick<RealtimeOptions, "baseUrl">>): RealtimeClient;
-    /**
-     * Page through any limit/offset or cursor-based endpoint as an async iterable.
-     *
-     *   for await (const s of client.paginate({
-     *     fetch: ({ limit, offset }) =>
-     *       client.actor.getActorScrobbles({ did, limit, offset }),
-     *     pageSize: 50,
-     *   })) { ... }
-     */
-    paginate<T>(args: PaginateArgs<T>): AsyncIterable<T> & {
-        toArray(): Promise<T[]>;
-    };
-    /**
-     * Direct escape hatch — call any XRPC endpoint by NSID.
-     *
-     * Known NSIDs (string literals) are typed via the generated `Endpoints`
-     * map; arbitrary strings fall back to `unknown` (override with `<T>`).
-     */
-    xrpc<K extends keyof Endpoints>(nsid: K, method?: "GET" | "POST", opts?: XrpcOpts): Promise<Endpoints[K]>;
-    xrpc<T = unknown>(nsid: string, method?: "GET" | "POST", opts?: XrpcOpts): Promise<T>;
-    static builder(): RockskyClientBuilder;
-    private optionsSnapshot;
+    private rpc;
+    /** Build a read client against an AppView base URL (defaults to {@link DEFAULT_APPVIEW}). */
+    constructor(appview?: string);
+    private query;
+    /** An actor's detailed profile. `actor` is a handle or DID. */
+    profile(actor: string): Promise<ActorProfileViewDetailed>;
+    /** An actor's scrobbles, newest first. */
+    scrobbles(actor: string, limit?: number, offset?: number): Promise<ScrobbleViewBasic[]>;
+    /** An actor's most-played songs. */
+    songs(actor: string, limit?: number, offset?: number): Promise<SongViewBasic[]>;
+    /** An actor's most-played albums. */
+    albums(actor: string, limit?: number, offset?: number): Promise<AlbumViewBasic[]>;
+    /** An actor's most-played artists. */
+    artists(actor: string, limit?: number, offset?: number): Promise<ArtistViewBasic[]>;
+    /** The platform-wide top tracks chart. */
+    topTracks(limit?: number, offset?: number): Promise<SongViewBasic[]>;
+    /** The platform-wide top artists chart. */
+    topArtists(limit?: number, offset?: number): Promise<ArtistViewBasic[]>;
+    /** Full-text search across songs, albums, artists, playlists, actors. */
+    search(query: string): Promise<FeedSearchResultsView>;
+    /** Platform-wide totals. */
+    globalStats(): Promise<StatsGlobalStatsView>;
 }
-/**
- * Fluent builder.
- *
- *   const client = RockskyClient.builder()
- *     .baseUrl("https://api.rocksky.app")
- *     .auth(() => loadToken())
- *     .timeout(10_000)
- *     .retries(3)
- *     .userAgent("my-app/1.0")
- *     .build();
- */
-export declare class RockskyClientBuilder {
-    private readonly opts;
-    baseUrl(url: string): this;
-    auth(auth: AuthProvider): this;
-    bearer(token: string): this;
-    fetch(impl: FetchLike): this;
-    header(key: string, value: string): this;
-    headers(headers: Record<string, string>): this;
-    userAgent(ua: string): this;
-    timeout(ms: number): this;
-    retries(n: number): this;
-    retryDelay(ms: number): this;
-    build(): RockskyClient;
-}
-/** Convenience factory — equivalent to `new RockskyClient(options)`. */
-export declare function createClient(options?: ClientOptions): RockskyClient;
-export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,qBAAqB,EAOrB,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAE9B,mDAAmD;AACnD,eAAO,MAAM,eAAe,4BAA4B,CAAC;AAEzD,wEAAwE;AACxE,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAAS;IAEpB,6FAA6F;gBACjF,OAAO,GAAE,MAAwB;YAI/B,KAAK;IAUnB,+DAA+D;IAC/D,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAIzD,0CAA0C;IACpC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IASpF,oCAAoC;IAC9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAS5E,qCAAqC;IAC/B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAS9E,sCAAsC;IAChC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAShF,0CAA0C;IACpC,SAAS,CAAC,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAKjE,2CAA2C;IACrC,UAAU,CAAC,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAKpE,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIrD,4BAA4B;IAC5B,WAAW,IAAI,OAAO,CAAC,oBAAoB,CAAC;CAG7C"}

package/dist/dedup.d.ts

@@ -0,0 +1,38 @@
+/** What an {@link RockskyIndex.indexCar} pass added. */
+export interface IndexStats {
+    artists: number;
+    albums: number;
+    songs: number;
+    scrobbles: number;
+}
+export declare function totalIndexed(s: IndexStats): number;
+/**
+ * Local duplicate-prevention mirror of a user's repo, keyed by Rocksky's
+ * identity hashes, backed by an embedded LevelDB (classic-level). Built from the
+ * repo CAR by {@link Agent.syncRepo} and kept live by {@link Agent.hydrateFromJetstream}.
+ */
+export declare class RockskyIndex {
+    private db;
+    constructor(path: string);
+    /** Open the database (call before use). */
+    open(): Promise<void>;
+    /** Close the database. */
+    close(): Promise<void>;
+    private get;
+    songUri(did: string, title: string, artist: string, album: string): Promise<string | undefined>;
+    albumUri(did: string, album: string, albumArtist: string): Promise<string | undefined>;
+    artistUri(did: string, albumArtist: string): Promise<string | undefined>;
+    scrobbleUri(did: string, title: string, artist: string, album: string, secs: number): Promise<string | undefined>;
+    private putPrimary;
+    recordSong(did: string, title: string, artist: string, album: string, uri: string): Promise<void>;
+    recordAlbum(did: string, album: string, albumArtist: string, uri: string): Promise<void>;
+    recordArtist(did: string, albumArtist: string, uri: string): Promise<void>;
+    recordScrobble(did: string, title: string, artist: string, album: string, secs: number, uri: string): Promise<void>;
+    cursor(did: string): Promise<number>;
+    setCursor(did: string, timeUS: number): Promise<void>;
+    /** Ingest a full repo CAR for `did`, indexing song/album/artist/scrobble. */
+    indexCar(did: string, car: Uint8Array): Promise<IndexStats>;
+    /** Apply a single Jetstream commit event to the index. */
+    applyCommit(did: string, col: string, operation: string, rkey: string, record: Record<string, unknown> | undefined): Promise<void>;
+}
+//# sourceMappingURL=dedup.d.ts.map

package/dist/dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../src/dedup.ts"],"names":[],"mappings":"AAaA,wDAAwD;AACxD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAElD;AA+BD;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,EAAE,CAA+B;gBAE7B,IAAI,EAAE,MAAM;IAIxB,2CAA2C;IAC3C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAGrB,0BAA0B;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAIR,GAAG;IAQjB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAG/F,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAGtF,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAGxE,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;YAInG,UAAU;IAOxB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAGjG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAGxF,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAG1E,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAG9B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,6EAA6E;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAoCjE,0DAA0D;IACpD,WAAW,CACf,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,OAAO,CAAC,IAAI,CAAC;CAiBjB"}

package/dist/errors.d.ts

@@ -1,26 +1,6 @@
+/** Error thrown when a Rocksky XRPC call returns a non-2xx `{ error, message }`. */
 export declare class RockskyError extends Error {
-    readonly cause?: unknown;
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-export declare class RockskyHttpError extends RockskyError {
-    readonly status: number;
-    readonly statusText: string;
-    readonly url: string;
-    readonly body: unknown;
-    constructor(args: {
-        status: number;
-        statusText: string;
-        url: string;
-        body: unknown;
-        message?: string;
-    });
-}
-export declare class RockskyTimeoutError extends RockskyError {
-    constructor(ms: number);
-}
-export declare class RockskyAuthError extends RockskyError {
-    constructor(message?: string);
+    readonly kind?: string;
+    constructor(payload: unknown);
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBACb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAK3D;AAED,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,OAAO,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;CAWF;AAED,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,EAAE,EAAE,MAAM;CAIvB;AAED,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,SAA4B;CAIhD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBACX,OAAO,EAAE,OAAO;CAM7B"}