@rocksky/sdk 0.3.0 → 0.4.0

package/dist/jetstream.d.ts

@@ -0,0 +1,17 @@
+import type { RockskyIndex } from "./dedup.js";
+/** The four public Bluesky Jetstream servers. */
+export declare const DEFAULT_JETSTREAM_SERVERS: string[];
+export interface JetstreamOptions {
+    /** Servers to connect to at once (defaults to {@link DEFAULT_JETSTREAM_SERVERS}). */
+    servers?: string[];
+    /** Cancels the hydration and closes all connections when aborted. */
+    signal?: AbortSignal;
+}
+/**
+ * Hydrate `idx` from the Bluesky Jetstream firehose for `did`, connecting to
+ * every server at once, filtered to app.rocksky.* + this DID. A shared watermark
+ * de-duplicates the overlap between servers and is the reconnect cursor. Resolves
+ * when opts.signal aborts; each source reconnects with backoff.
+ */
+export declare function runJetstream(idx: RockskyIndex, did: string, opts?: JetstreamOptions): Promise<void>;
+//# sourceMappingURL=jetstream.d.ts.map

package/dist/jetstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jetstream.d.ts","sourceRoot":"","sources":["../src/jetstream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,iDAAiD;AACjD,eAAO,MAAM,yBAAyB,UAKrC,CAAC;AAIF,MAAM,WAAW,gBAAgB;IAC/B,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,qEAAqE;IACrE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmBD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7G"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rocksky/sdk",
-  "version": "0.3.0",
-  "description": "TypeScript SDK for the Rocksky XRPC API",
+  "version": "0.4.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": {
     "type": "git",
@@ -31,16 +31,9 @@
   "scripts": {
     "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm --external none && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
-    "test": "bun test",
-    "test:watch": "bun test --watch",
     "typecheck": "tsc --noEmit",
-    "example:quickstart": "bun run examples/quickstart.ts",
-    "example:builder": "bun run examples/builder.ts",
-    "example:pipe": "bun run examples/pipe.ts",
-    "example:scrobble": "bun run examples/scrobble.ts",
-    "example:pagination": "bun run examples/pagination.ts",
-    "example:paginate": "bun run examples/paginate.ts",
-    "example:realtime": "bun run examples/realtime.ts"
+    "test": "bun test",
+    "example": "bun run examples/native.ts"
   },
   "keywords": [
     "rocksky",
@@ -59,7 +52,18 @@
     "api"
   ],
   "devDependencies": {
+    "@atcute/atproto": "^4.0.3",
     "@types/bun": "latest",
     "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "@atcute/car": "^6.0.2",
+    "@atcute/cbor": "^2.3.6",
+    "@atcute/cid": "^2.4.2",
+    "@atcute/client": "^5.1.1",
+    "@atcute/identity": "^2.0.2",
+    "@atcute/identity-resolver": "^2.0.1",
+    "@atcute/password-session": "^1.0.2",
+    "classic-level": "^3.0.0"
   }
 }

package/src/agent.ts

@@ -0,0 +1,232 @@
+import { Client } from "@atcute/client";
+import {
+  CompositeDidDocumentResolver,
+  CompositeHandleResolver,
+  DohJsonHandleResolver,
+  LocalActorResolver,
+  PlcDidDocumentResolver,
+  WebDidDocumentResolver,
+  WellKnownHandleResolver,
+} from "@atcute/identity-resolver";
+import { PasswordSession } from "@atcute/password-session";
+
+import { RockskyError } from "./errors.js";
+import type {
+  AlbumRecord,
+  ArtistRecord,
+  ActorTrackView,
+  ScrobbleRecord,
+  SongRecord,
+} from "./generated/types.js";
+import type { IndexStats, RockskyIndex } from "./dedup.js";
+import { runJetstream, type JetstreamOptions } from "./jetstream.js";
+
+// Collection NSIDs written by the agent.
+const C_SCROBBLE = "app.rocksky.scrobble";
+const C_SONG = "app.rocksky.song";
+const C_ALBUM = "app.rocksky.album";
+const C_ARTIST = "app.rocksky.artist";
+const C_LIKE = "app.rocksky.like";
+const C_FOLLOW = "app.rocksky.graph.follow";
+const C_SHOUT = "app.rocksky.shout";
+const C_STATUS = "app.rocksky.actor.status";
+
+function actorResolver(): LocalActorResolver {
+  return new LocalActorResolver({
+    handleResolver: new CompositeHandleResolver({
+      methods: {
+        dns: new DohJsonHandleResolver({ dohUrl: "https://mozilla.cloudflare-dns.com/dns-query" }),
+        http: new WellKnownHandleResolver(),
+      },
+    }),
+    didDocumentResolver: new CompositeDidDocumentResolver({
+      methods: { plc: new PlcDidDocumentResolver(), web: new WebDidDocumentResolver() },
+    }),
+  });
+}
+
+function nowISO(): string {
+  return new Date().toISOString();
+}
+
+// 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.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 class Agent {
+  private idx?: RockskyIndex;
+
+  private constructor(
+    private rpc: Client,
+    readonly did: string,
+    readonly session: PasswordSession,
+    private pds: string,
+  ) {}
+
+  /**
+   * Resolve the account's PDS, authenticate with an app password, and return an
+   * Agent. `identifier` is a handle or DID.
+   */
+  static async login(identifier: string, password: string): Promise<Agent> {
+    const actor = await actorResolver().resolve(identifier as never);
+    const session = await PasswordSession.login({ service: actor.pds, identifier, password });
+    return new Agent(new Client({ handler: session }), session.did, session, actor.pds);
+  }
+
+  /** Attach a local dedup index — write verbs then skip records that already exist. */
+  useIndex(idx: RockskyIndex): void {
+    this.idx = idx;
+  }
+
+  /**
+   * 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}.
+   */
+  async syncRepo(): Promise<IndexStats> {
+    if (!this.idx) throw new Error("no dedup index attached (call useIndex)");
+    const url = `${this.pds}/xrpc/com.atproto.sync.getRepo?did=${encodeURIComponent(this.did)}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`getRepo: ${res.status}`);
+    const car = new Uint8Array(await res.arrayBuffer());
+    return this.idx.indexCar(this.did, car);
+  }
+
+  /**
+   * 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> {
+    if (!this.idx) throw new Error("no dedup index attached (call useIndex)");
+    return runJetstream(this.idx, this.did, opts);
+  }
+
+  private async create(collection: string, record: Record<string, unknown>): Promise<string> {
+    const res = await this.rpc.post("com.atproto.repo.createRecord" as never, {
+      input: { repo: this.did, collection, record: { ...record, $type: collection } },
+    } as never);
+    if (!res.ok) throw new RockskyError(res.data);
+    return (res.data as { uri: string }).uri;
+  }
+
+  private async putRecord(collection: string, rkey: string, record: Record<string, unknown>): Promise<string> {
+    const res = await this.rpc.post("com.atproto.repo.putRecord" as never, {
+      input: { repo: this.did, collection, rkey, record: { ...record, $type: collection } },
+    } as never);
+    if (!res.ok) throw new RockskyError(res.data);
+    return (res.data as { uri: string }).uri;
+  }
+
+  /** Delete a record by collection + rkey. */
+  async delete(collection: string, rkey: string): Promise<void> {
+    const res = await this.rpc.post("com.atproto.repo.deleteRecord" as never, {
+      input: { repo: this.did, collection, rkey },
+    } as never);
+    if (!res.ok) throw new RockskyError(res.data);
+  }
+
+  /** Scrobble a play (app.rocksky.scrobble). createdAt defaults to now. */
+  async scrobble(rec: ScrobbleInput): Promise<string> {
+    const record = { ...rec, createdAt: rec.createdAt || nowISO() };
+    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);
+      if (existing) return existing;
+    }
+    const uri = await this.create(C_SCROBBLE, record as Record<string, unknown>);
+    if (this.idx) {
+      const secs = Math.floor(Date.parse(record.createdAt) / 1000);
+      await this.idx.recordScrobble(this.did, record.title!, record.artist!, record.album!, secs, uri);
+    }
+    return uri;
+  }
+
+  /** Create a canonical track record (app.rocksky.song). */
+  async createSong(rec: SongInput): Promise<string> {
+    const record = { ...rec, createdAt: rec.createdAt || nowISO() };
+    if (this.idx) {
+      const existing = await this.idx.songUri(this.did, record.title!, record.artist!, record.album!);
+      if (existing) return existing;
+    }
+    const uri = await this.create(C_SONG, record as Record<string, unknown>);
+    if (this.idx) await this.idx.recordSong(this.did, record.title!, record.artist!, record.album!, uri);
+    return uri;
+  }
+
+  /** Create an album record (app.rocksky.album). `artist` is the album artist. */
+  async createAlbum(rec: AlbumInput): Promise<string> {
+    const record = { ...rec, createdAt: rec.createdAt || nowISO() };
+    if (this.idx) {
+      const existing = await this.idx.albumUri(this.did, record.title!, record.artist!);
+      if (existing) return existing;
+    }
+    const uri = await this.create(C_ALBUM, record as Record<string, unknown>);
+    if (this.idx) await this.idx.recordAlbum(this.did, record.title!, record.artist!, uri);
+    return uri;
+  }
+
+  /** Create an artist record (app.rocksky.artist). */
+  async createArtist(rec: ArtistInput): Promise<string> {
+    const record = { ...rec, createdAt: rec.createdAt || nowISO() };
+    if (this.idx) {
+      const existing = await this.idx.artistUri(this.did, record.name!);
+      if (existing) return existing;
+    }
+    const uri = await this.create(C_ARTIST, record as Record<string, unknown>);
+    if (this.idx) await this.idx.recordArtist(this.did, record.name!, uri);
+    return uri;
+  }
+
+  /** Like a record by strong reference (uri + cid). Returns the like URI. */
+  like(uri: string, cid: string): Promise<string> {
+    return this.create(C_LIKE, { subject: { uri, cid }, createdAt: nowISO() });
+  }
+
+  /** Follow an account by DID. Returns the follow URI. */
+  follow(did: string): Promise<string> {
+    return this.create(C_FOLLOW, { subject: did, createdAt: nowISO() });
+  }
+
+  /** Post a shout on a subject. Returns the shout URI. */
+  shout(subjectUri: string, subjectCid: string, message: string): Promise<string> {
+    return this.create(C_SHOUT, { subject: { uri: subjectUri, cid: subjectCid }, message, createdAt: nowISO() });
+  }
+
+  /** Reply to a shout, with a parent strong-ref. */
+  replyShout(
+    subjectUri: string,
+    subjectCid: string,
+    parentUri: string,
+    parentCid: string,
+    message: string,
+  ): Promise<string> {
+    return this.create(C_SHOUT, {
+      subject: { uri: subjectUri, cid: subjectCid },
+      parent: { uri: parentUri, cid: parentCid },
+      message,
+      createdAt: nowISO(),
+    });
+  }
+
+  /** Upsert the actor's now-playing status singleton (rkey "self"). */
+  setNowPlaying(track: ActorTrackView): Promise<string> {
+    return this.putRecord(C_STATUS, "self", { track, startedAt: nowISO() });
+  }
+
+  /** Delete the actor's now-playing status singleton. */
+  clearNowPlaying(): Promise<void> {
+    return this.delete(C_STATUS, "self");
+  }
+}

package/src/client.ts

@@ -1,252 +1,108 @@
-import { buildConfig, type HttpClientConfig, xrpcCall } from "./http.js";
-import { makeCall } from "./namespaces/_helpers.js";
-import {
-  type PaginateArgs,
-  paginate as paginateFn,
-} from "./paginate.js";
-import {
-  RealtimeClient,
-  type RealtimeOptions,
-  createRealtimeClient,
-} 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 { Client, simpleFetchHandler } from "@atcute/client";
 
+import { RockskyError } from "./errors.js";
+import type {
+  ActorProfileViewDetailed,
+  AlbumViewBasic,
+  ArtistViewBasic,
+  FeedSearchResultsView,
+  GetActorAlbumsOutput,
+  GetActorArtistsOutput,
+  GetActorScrobblesOutput,
+  GetActorSongsOutput,
+  GetTopArtistsOutput,
+  GetTopTracksOutput,
+  ScrobbleViewBasic,
+  SongViewBasic,
+  StatsGlobalStatsView,
+} from "./generated/types.js";
+
+/** The default public Rocksky AppView base URL. */
+export const DEFAULT_APPVIEW = "https://api.rocksky.app";
+
+/** Unauthenticated read client over the public Rocksky AppView XRPC. */
 export 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;
+  private rpc: Client;
 
-  constructor(options: ClientOptions = {}) {
-    this.config = buildConfig(options);
-    const call = makeCall(this.config);
-
-    this.actor = new ActorNamespace(call);
-    this.album = new AlbumNamespace(call);
-    this.apikey = new ApikeyNamespace(call);
-    this.artist = new ArtistNamespace(call);
-    this.charts = new ChartsNamespace(call);
-    this.dropbox = new DropboxNamespace(call);
-    this.feed = new FeedNamespace(call);
-    this.googledrive = new GoogleDriveNamespace(call);
-    this.graph = new GraphNamespace(call);
-    this.like = new LikeNamespace(call);
-    this.mirror = new MirrorNamespace(call);
-    this.player = new PlayerNamespace(call);
-    this.playlist = new PlaylistNamespace(call);
-    this.scrobble = new ScrobbleNamespace(call);
-    this.shout = new ShoutNamespace(call);
-    this.song = new SongNamespace(call);
-    this.spotify = new SpotifyNamespace(call);
-    this.stats = new StatsNamespace(call);
+  /** Build a read client against an AppView base URL (defaults to {@link DEFAULT_APPVIEW}). */
+  constructor(appview: string = DEFAULT_APPVIEW) {
+    this.rpc = new Client({ handler: simpleFetchHandler({ service: appview }) });
   }
 
-  /** Build a one-off authenticated copy without mutating this client. */
-  withAuth(auth: AuthProvider): RockskyClient {
-    return new RockskyClient({
-      ...this.optionsSnapshot(),
-      auth,
-    });
+  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)) {
+      if (v !== undefined && v !== "") clean[k] = v;
+    }
+    const res = await this.rpc.get(nsid as never, { params: clean } as never);
+    if (!res.ok) throw new RockskyError(res.data);
+    return res.data as T;
   }
 
-  /** Build a copy with an overridden base URL. */
-  withBaseUrl(baseUrl: string): RockskyClient {
-    return new RockskyClient({
-      ...this.optionsSnapshot(),
-      baseUrl,
-    });
+  /** An actor's detailed profile. `actor` is a handle or DID. */
+  profile(actor: string): Promise<ActorProfileViewDetailed> {
+    return this.query("app.rocksky.actor.getProfile", { did: actor });
   }
 
-  /**
-   * 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 {
-    return createRealtimeClient({
-      baseUrl: this.config.baseUrl,
-      ...options,
+  /** An actor's scrobbles, newest first. */
+  async scrobbles(actor: string, limit = 50, offset = 0): Promise<ScrobbleViewBasic[]> {
+    const out = await this.query<GetActorScrobblesOutput>("app.rocksky.actor.getActorScrobbles", {
+      did: actor,
+      limit,
+      offset,
     });
+    return out.scrobbles ?? [];
   }
 
-  /**
-   * 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>) {
-    return paginateFn(args);
-  }
-
-  /**
-   * 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>;
-  xrpc(
-    nsid: string,
-    method: "GET" | "POST" = "GET",
-    opts: XrpcOpts = {},
-  ): Promise<unknown> {
-    return xrpcCall(this.config, nsid, method, opts);
-  }
-
-  static builder(): RockskyClientBuilder {
-    return new RockskyClientBuilder();
-  }
-
-  private optionsSnapshot(): ClientOptions {
-    return {
-      baseUrl: this.config.baseUrl,
-      auth: this.config.auth,
-      fetch: this.config.fetch,
-      headers: this.config.headers,
-      timeoutMs: this.config.timeoutMs,
-      retries: this.config.retries,
-      retryDelayMs: this.config.retryDelayMs,
-    };
-  }
-}
-
-/**
- * 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 class RockskyClientBuilder {
-  private readonly opts: ClientOptions = {};
-
-  baseUrl(url: string): this {
-    this.opts.baseUrl = url;
-    return this;
-  }
-
-  auth(auth: AuthProvider): this {
-    this.opts.auth = auth;
-    return this;
-  }
-
-  bearer(token: string): this {
-    this.opts.auth = token;
-    return this;
-  }
-
-  fetch(impl: FetchLike): this {
-    this.opts.fetch = impl;
-    return this;
-  }
-
-  header(key: string, value: string): this {
-    this.opts.headers = { ...this.opts.headers, [key]: value };
-    return this;
+  /** An actor's most-played songs. */
+  async songs(actor: string, limit = 50, offset = 0): Promise<SongViewBasic[]> {
+    const out = await this.query<GetActorSongsOutput>("app.rocksky.actor.getActorSongs", {
+      did: actor,
+      limit,
+      offset,
+    });
+    return out.songs ?? [];
   }
 
-  headers(headers: Record<string, string>): this {
-    this.opts.headers = { ...this.opts.headers, ...headers };
-    return this;
+  /** An actor's most-played albums. */
+  async albums(actor: string, limit = 50, offset = 0): Promise<AlbumViewBasic[]> {
+    const out = await this.query<GetActorAlbumsOutput>("app.rocksky.actor.getActorAlbums", {
+      did: actor,
+      limit,
+      offset,
+    });
+    return out.albums ?? [];
   }
 
-  userAgent(ua: string): this {
-    this.opts.userAgent = ua;
-    return this;
+  /** An actor's most-played artists. */
+  async artists(actor: string, limit = 50, offset = 0): Promise<ArtistViewBasic[]> {
+    const out = await this.query<GetActorArtistsOutput>("app.rocksky.actor.getActorArtists", {
+      did: actor,
+      limit,
+      offset,
+    });
+    return out.artists ?? [];
   }
 
-  timeout(ms: number): this {
-    this.opts.timeoutMs = ms;
-    return this;
+  /** The platform-wide top tracks chart. */
+  async topTracks(limit = 50, offset = 0): Promise<SongViewBasic[]> {
+    const out = await this.query<GetTopTracksOutput>("app.rocksky.charts.getTopTracks", { limit, offset });
+    return out.tracks ?? [];
   }
 
-  retries(n: number): this {
-    this.opts.retries = n;
-    return this;
+  /** The platform-wide top artists chart. */
+  async topArtists(limit = 50, offset = 0): Promise<ArtistViewBasic[]> {
+    const out = await this.query<GetTopArtistsOutput>("app.rocksky.charts.getTopArtists", { limit, offset });
+    return out.artists ?? [];
   }
 
-  retryDelay(ms: number): this {
-    this.opts.retryDelayMs = ms;
-    return this;
+  /** Full-text search across songs, albums, artists, playlists, actors. */
+  search(query: string): Promise<FeedSearchResultsView> {
+    return this.query("app.rocksky.feed.search", { query });
   }
 
-  build(): RockskyClient {
-    return new RockskyClient(this.opts);
+  /** Platform-wide totals. */
+  globalStats(): Promise<StatsGlobalStatsView> {
+    return this.query("app.rocksky.stats.getGlobalStats", {});
   }
 }
-
-/** Convenience factory — equivalent to `new RockskyClient(options)`. */
-export function createClient(options: ClientOptions = {}): RockskyClient {
-  return new RockskyClient(options);
-}