@rocksky/sdk 0.10.1 → 0.11.0

package/dist/agent.d.ts

@@ -2,6 +2,55 @@ import { PasswordSession } from "@atcute/password-session";
 import type { AlbumRecord, ArtistRecord, ActorTrackView, ScrobbleRecord, ShoutGif, SongRecord } from "./generated/types.js";
 import type { IndexStats, RockskyIndex } from "./dedup.js";
 import { type JetstreamOptions } from "./jetstream.js";
+/**
+ * The highest sustained writes-per-hour that still fits Bluesky's write-point
+ * budget. On the official Bluesky PDS this is a hard ceiling the Agent will not
+ * let any caller exceed; self-hosted PDSes may allow more (or none).
+ */
+export declare const MAX_SAFE_WRITES_PER_HOUR: number;
+export declare const DEFAULT_MATCH_SONG_PER_HOUR: number;
+/** Options for {@link Agent.configureRateLimit}. */
+export interface RateLimitOptions {
+    /**
+     * Target writes (createRecord/putRecord/deleteRecord) per hour. Omitted →
+     * {@link MAX_SAFE_WRITES_PER_HOUR}. On the official Bluesky PDS this is
+     * clamped to the safe ceiling; on a self-hosted PDS it is honored as given.
+     * Ignored when `disabled` is true.
+     */
+    writesPerHour?: number;
+    /**
+     * Turn the client-side *write* throttle off entirely. Honored on self-hosted
+     * PDSes (useful when you run your own PDS with its own limits). IGNORED —
+     * forced back on at the safe rate — when the account lives on the official
+     * Bluesky PDS (*.bsky.network), whose budget is enforced server-side.
+     *
+     * NOTE: this never affects the Rocksky AppView `matchSong` throttle, which is
+     * always enforced (see {@link RateLimitOptions.matchSongPerHour}).
+     */
+    disabled?: boolean;
+    /**
+     * Target Rocksky AppView `matchSong` calls per hour. ALWAYS enforced — a
+     * self-hosted PDS grants no extra AppView capacity — so `disabled` never turns
+     * it off; this only tunes the rate. Omitted → keep the current value
+     * (default {@link DEFAULT_MATCH_SONG_PER_HOUR}). Non-positive values are ignored.
+     */
+    matchSongPerHour?: number;
+}
+/** The effective throttle state after {@link Agent.configureRateLimit} applies policy. */
+export interface RateLimitState {
+    /** Whether the *write* throttle is active. */
+    enabled: boolean;
+    /** Effective writes/hour cap (Infinity when disabled). */
+    writesPerHour: number;
+    /** True when `disabled` was requested but overridden by the bsky.network guard. */
+    forcedOn: boolean;
+    /** True when a requested `writesPerHour` was clamped to the safe ceiling. */
+    capped: boolean;
+    /** The resolved PDS host the decision was based on. */
+    pdsHost: string;
+    /** Effective Rocksky AppView matchSong rate — always enforced, never disabled. */
+    matchSongPerHour: number;
+}
 /** Input for {@link Agent.scrobble} (createdAt defaults to now). */
 export type ScrobbleInput = Omit<ScrobbleRecord, "createdAt"> & {
     createdAt?: string;
@@ -42,7 +91,31 @@ export declare class Agent {
     readonly session: PasswordSession;
     private pds;
     private idx?;
+    private writeGate;
+    private matchGate;
+    private matchSongPerHour;
+    /** Lower-case hostname of the account's resolved PDS (e.g. "pds.example.com"). */
+    readonly pdsHost: string;
     private constructor();
+    /**
+     * Whether the account lives on the official Bluesky PDS (*.bsky.network).
+     * Its write budget is enforced server-side, so the client-side throttle can
+     * never be disabled for these hosts.
+     */
+    get isOfficialBlueskyPds(): boolean;
+    /**
+     * Configure the client-side write throttle and return the effective state.
+     *
+     * Policy — the *.bsky.network guard is authoritative and cannot be bypassed:
+     *  - `disabled: true` turns the throttle off on a self-hosted PDS, but on the
+     *    official Bluesky PDS it is ignored and the throttle stays on at the safe
+     *    rate (`forcedOn: true`).
+     *  - `writesPerHour` is honored as given on a self-hosted PDS, but clamped to
+     *    {@link MAX_SAFE_WRITES_PER_HOUR} on the official Bluesky PDS
+     *    (`capped: true` when clamped).
+     *  - Omitting both enables the throttle at the safe default rate.
+     */
+    configureRateLimit(opts?: RateLimitOptions): RateLimitState;
     /**
      * Resolve the account's PDS, authenticate with an app password, and return an
      * Agent. `identifier` is a handle or DID.

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAG3D,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,cAAc,EACd,QAAQ,EACR,UAAU,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AA+BrE,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACvF,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/E,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACjF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;;GAIG;AACH,qBAAa,KAAK;IAId,OAAO,CAAC,GAAG;IACX,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,OAAO,EAAE,eAAe;IACjC,OAAO,CAAC,GAAG;IANb,OAAO,CAAC,GAAG,CAAC,CAAe;IAE3B,OAAO;IAOP;;;OAGG;WACU,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAUxE,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAIjC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IASrC;;;;OAIG;IACH,oBAAoB,CAAC,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;YAKlD,MAAM;YAQN,SAAS;IAQvB,4CAA4C;IACtC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7D;;;;;;;OAOG;IACG,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBnD;;;;;;;OAOG;YACW,uBAAuB;IA2BrC;;;;gFAI4E;IACtE,aAAa,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsCjF,0DAA0D;IACpD,UAAU,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAWjD,gFAAgF;IAC1E,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAWnD,oDAAoD;IAC9C,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAWrD,2EAA2E;IAC3E,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C,wDAAwD;IACxD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpC;;mBAEe;IACf,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAShG;iFAC6E;IAC7E,UAAU,CACR,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,QAAQ,GACb,OAAO,CAAC,MAAM,CAAC;IAUlB,qEAAqE;IACrE,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD,uDAAuD;IACvD,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.ratelimit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent.ratelimit.test.d.ts.map

package/dist/agent.ratelimit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.ratelimit.test.d.ts","sourceRoot":"","sources":["../src/agent.ratelimit.test.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -11,7 +11,7 @@
 export { RockskyClient, DEFAULT_APPVIEW, Interval } from "./client.js";
 export type { DateInterval } from "./client.js";
 export { RockskyLibrary } from "./library.js";
-export { Agent, type ScrobbleInput, type ScrobbleMatchInput, type SongInput, type AlbumInput, type ArtistInput, } from "./agent.js";
+export { Agent, MAX_SAFE_WRITES_PER_HOUR, DEFAULT_MATCH_SONG_PER_HOUR, type ScrobbleInput, type ScrobbleMatchInput, type SongInput, type AlbumInput, type ArtistInput, type RateLimitOptions, type RateLimitState, } from "./agent.js";
 export { RockskyIndex, totalIndexed, type IndexStats } from "./dedup.js";
 export { runJetstream, DEFAULT_JETSTREAM_SERVERS, type JetstreamOptions } from "./jetstream.js";
 export { RemotePlayer, DEFAULT_REMOTE_WS, type RemotePlayerOptions, type RemotePlayerHandlers, type RemoteNowPlaying, type RemoteQueueItem, type EnqueueCommand, } from "./remote-player.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,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,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,EACL,YAAY,EACZ,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC;AAChC,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,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EACL,KAAK,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,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,EACL,YAAY,EACZ,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC;AAChC,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

@@ -626,6 +626,38 @@ function actorResolver() {
 function nowISO() {
   return new Date().toISOString();
 }
+function hostOf(url) {
+  try {
+    return new URL(url).hostname.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+var PDS_WRITE_POINT_BUDGET_PER_HOUR = 5000;
+var POINTS_PER_WRITE = 3;
+var SAFETY_MARGIN = 0.9;
+var MAX_SAFE_WRITES_PER_HOUR = Math.floor(PDS_WRITE_POINT_BUDGET_PER_HOUR * SAFETY_MARGIN / POINTS_PER_WRITE);
+var APPVIEW_REQUEST_LIMIT = 1000;
+var APPVIEW_WINDOW_SECONDS = 30;
+var DEFAULT_MATCH_SONG_PER_HOUR = Math.floor(APPVIEW_REQUEST_LIMIT * SAFETY_MARGIN / APPVIEW_WINDOW_SECONDS * 3600);
+
+class RateGate {
+  nextAt = 0;
+  minIntervalMs = 0;
+  setRate(writesPerHour) {
+    this.minIntervalMs = writesPerHour && writesPerHour > 0 ? Math.ceil(3600000 / writesPerHour) : 0;
+  }
+  async take() {
+    if (this.minIntervalMs <= 0)
+      return;
+    const now = Date.now();
+    const at = Math.max(now, this.nextAt);
+    this.nextAt = at + this.minIntervalMs;
+    const delay = at - now;
+    if (delay > 0)
+      await new Promise((r) => setTimeout(r, delay));
+  }
+}
 
 class Agent {
   rpc;
@@ -633,11 +665,51 @@ class Agent {
   session;
   pds;
   idx;
+  writeGate = new RateGate;
+  matchGate = new RateGate;
+  matchSongPerHour = DEFAULT_MATCH_SONG_PER_HOUR;
+  pdsHost;
   constructor(rpc, did, session, pds) {
     this.rpc = rpc;
     this.did = did;
     this.session = session;
     this.pds = pds;
+    this.pdsHost = hostOf(pds);
+    this.matchGate.setRate(this.matchSongPerHour);
+  }
+  get isOfficialBlueskyPds() {
+    return this.pdsHost === "bsky.network" || this.pdsHost.endsWith(".bsky.network");
+  }
+  configureRateLimit(opts = {}) {
+    if (opts.matchSongPerHour !== undefined && opts.matchSongPerHour > 0) {
+      this.matchSongPerHour = opts.matchSongPerHour;
+      this.matchGate.setRate(this.matchSongPerHour);
+    }
+    const official = this.isOfficialBlueskyPds;
+    const state = (partial) => ({
+      ...partial,
+      pdsHost: this.pdsHost,
+      matchSongPerHour: this.matchSongPerHour
+    });
+    if (opts.disabled) {
+      if (official) {
+        const writesPerHour2 = Math.min(opts.writesPerHour ?? MAX_SAFE_WRITES_PER_HOUR, MAX_SAFE_WRITES_PER_HOUR);
+        this.writeGate.setRate(writesPerHour2);
+        return state({ enabled: true, writesPerHour: writesPerHour2, forcedOn: true, capped: false });
+      }
+      this.writeGate.setRate(null);
+      return state({ enabled: false, writesPerHour: Infinity, forcedOn: false, capped: false });
+    }
+    let writesPerHour = opts.writesPerHour ?? MAX_SAFE_WRITES_PER_HOUR;
+    if (!(writesPerHour > 0))
+      writesPerHour = MAX_SAFE_WRITES_PER_HOUR;
+    let capped = false;
+    if (official && writesPerHour > MAX_SAFE_WRITES_PER_HOUR) {
+      writesPerHour = MAX_SAFE_WRITES_PER_HOUR;
+      capped = true;
+    }
+    this.writeGate.setRate(writesPerHour);
+    return state({ enabled: true, writesPerHour, forcedOn: false, capped });
   }
   static async login(identifier, password) {
     const actor = await actorResolver().resolve(identifier);
@@ -664,6 +736,7 @@ class Agent {
     return runJetstream(this.idx, this.did, opts);
   }
   async create(collection, record) {
+    await this.writeGate.take();
     const res = await this.rpc.post("com.atproto.repo.createRecord", {
       input: { repo: this.did, collection, record: { ...record, $type: collection } }
     });
@@ -672,6 +745,7 @@ class Agent {
     return res.data.uri;
   }
   async putRecord(collection, rkey, record) {
+    await this.writeGate.take();
     const res = await this.rpc.post("com.atproto.repo.putRecord", {
       input: { repo: this.did, collection, rkey, record: { ...record, $type: collection } }
     });
@@ -680,6 +754,7 @@ class Agent {
     return res.data.uri;
   }
   async delete(collection, rkey) {
+    await this.writeGate.take();
     const res = await this.rpc.post("com.atproto.repo.deleteRecord", {
       input: { repo: this.did, collection, rkey }
     });
@@ -730,6 +805,7 @@ class Agent {
   async scrobbleMatch(input, appview) {
     const { title, artist, album, mbId, isrc, timestamp } = input;
     const { RockskyClient: RockskyClient2 } = await Promise.resolve().then(() => (init_client(), exports_client));
+    await this.matchGate.take();
     const m = await new RockskyClient2(appview).matchSong(title, artist, mbId, isrc);
     const s = (k) => m && typeof m[k] === "string" ? m[k] : undefined;
     const n = (k) => m && typeof m[k] === "number" ? m[k] : undefined;
@@ -1541,8 +1617,10 @@ export {
   RockskyClient,
   RemotePlayer,
   RemoteController,
+  MAX_SAFE_WRITES_PER_HOUR,
   Interval,
   DEFAULT_REMOTE_WS,
+  DEFAULT_MATCH_SONG_PER_HOUR,
   DEFAULT_JETSTREAM_SERVERS,
   DEFAULT_APPVIEW,
   Agent

package/dist/remote.d.ts

@@ -0,0 +1,3 @@
+export { RemotePlayer, DEFAULT_REMOTE_WS, type RemotePlayerOptions, type RemotePlayerHandlers, type RemoteNowPlaying, type RemoteQueueItem, type EnqueueCommand, } from "./remote-player.js";
+export { RemoteController, type RemoteControllerOptions, type RemoteControllerEvents, type RemoteDevice, type RemoteStatus, } from "./remote-controller.js";
+//# sourceMappingURL=remote.d.ts.map

package/dist/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC"}

package/dist/remote.js

@@ -0,0 +1,529 @@
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/remote-player.ts
+var DEFAULT_REMOTE_WS = "wss://api.rocksky.app/ws";
+
+class RemotePlayer {
+  opts;
+  ws = null;
+  deviceId = "";
+  stopped = false;
+  heartbeat;
+  reconnectTimer;
+  url;
+  heartbeatMs;
+  reconnectMs;
+  getToken;
+  debug;
+  handlers = {};
+  lastTrack = null;
+  lastStatus = null;
+  lastQueue = null;
+  constructor(opts) {
+    this.opts = opts;
+    this.url = opts.url ?? DEFAULT_REMOTE_WS;
+    this.heartbeatMs = opts.heartbeatMs ?? 1e4;
+    this.reconnectMs = opts.reconnectMs ?? 3000;
+    this.getToken = typeof opts.token === "function" ? opts.token : () => opts.token;
+    this.debug = opts.debug ?? (() => {});
+  }
+  on(event, handler) {
+    this.handlers[event] = handler;
+    return this;
+  }
+  get id() {
+    return this.deviceId;
+  }
+  connect() {
+    this.stopped = false;
+    this.open();
+  }
+  disconnect() {
+    this.stopped = true;
+    if (this.reconnectTimer)
+      clearTimeout(this.reconnectTimer);
+    if (this.heartbeat)
+      clearInterval(this.heartbeat);
+    try {
+      this.ws?.close();
+    } catch {}
+    this.ws = null;
+  }
+  setNowPlaying(track) {
+    this.lastTrack = track;
+    this.send({
+      type: "message",
+      device_id: this.deviceId,
+      token: this.getToken(),
+      data: {
+        type: "track",
+        title: track.title,
+        artist: track.artist,
+        album: track.album,
+        album_artist: track.albumArtist ?? track.artist,
+        length: track.durationMs ?? 0,
+        elapsed: track.elapsedMs ?? 0,
+        duration_ms: track.durationMs ?? 0,
+        album_art: track.albumArt,
+        is_playing: track.isPlaying ?? true,
+        device_name: this.opts.name
+      }
+    });
+  }
+  setStatus(status) {
+    const code = status === "playing" ? 1 : status === "paused" ? 2 : 0;
+    this.lastStatus = code;
+    this.send({
+      type: "message",
+      device_id: this.deviceId,
+      token: this.getToken(),
+      data: { type: "status", status: code }
+    });
+  }
+  setQueue(items, index) {
+    this.lastQueue = { items, index };
+    this.send({
+      type: "message",
+      device_id: this.deviceId,
+      token: this.getToken(),
+      data: {
+        type: "queue",
+        index,
+        queue: items.map((t) => ({
+          uploadId: t.uploadId,
+          trackId: t.trackId,
+          title: t.title,
+          artist: t.artist,
+          album: t.album,
+          album_artist: t.albumArtist,
+          album_art: t.albumArt,
+          duration: t.durationMs,
+          song_uri: t.songUri,
+          album_uri: t.albumUri,
+          track_number: t.trackNumber
+        }))
+      }
+    });
+  }
+  send(payload) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      try {
+        this.ws.send(JSON.stringify(payload));
+      } catch (e) {
+        this.debug("send error", e);
+      }
+    }
+  }
+  open() {
+    if (this.stopped)
+      return;
+    const token = this.getToken();
+    if (!token) {
+      this.reconnectTimer = setTimeout(() => this.open(), this.reconnectMs);
+      return;
+    }
+    let ws;
+    try {
+      ws = new WebSocket(this.url);
+    } catch (e) {
+      this.debug("connect failed", e);
+      this.reconnectTimer = setTimeout(() => this.open(), this.reconnectMs);
+      return;
+    }
+    this.ws = ws;
+    ws.onopen = () => {
+      this.debug("connected");
+      this.send({ type: "register", clientName: this.opts.name, token: this.getToken() });
+      if (this.heartbeat)
+        clearInterval(this.heartbeat);
+      this.heartbeat = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN)
+          ws.send("ping");
+      }, this.heartbeatMs);
+    };
+    ws.onmessage = (ev) => {
+      if (ev.data === "pong")
+        return;
+      let msg;
+      try {
+        msg = JSON.parse(ev.data);
+      } catch {
+        return;
+      }
+      this.handle(msg);
+    };
+    ws.onerror = () => {
+      try {
+        ws.close();
+      } catch {}
+    };
+    ws.onclose = () => {
+      this.debug("disconnected");
+      if (this.heartbeat)
+        clearInterval(this.heartbeat);
+      if (this.ws === ws)
+        this.ws = null;
+      this.deviceId = "";
+      if (!this.stopped) {
+        if (this.reconnectTimer)
+          clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = setTimeout(() => this.open(), this.reconnectMs);
+      }
+    };
+  }
+  handle(msg) {
+    if (msg.status === "registered" && typeof msg.deviceId === "string") {
+      this.deviceId = msg.deviceId;
+      this.debug("registered", this.deviceId);
+      this.resync();
+      return;
+    }
+    if (msg.type === "command") {
+      this.dispatch(msg);
+      return;
+    }
+  }
+  dispatch(msg) {
+    const h = this.handlers;
+    switch (msg.action) {
+      case "play":
+        h.play?.();
+        break;
+      case "pause":
+        h.pause?.();
+        break;
+      case "next":
+        h.next?.();
+        break;
+      case "previous":
+        h.previous?.();
+        break;
+      case "seek": {
+        const a = msg.args;
+        const pos = typeof a === "number" ? a : a?.position ?? 0;
+        h.seek?.(pos);
+        break;
+      }
+      case "queue_jump":
+        h.queueJump?.(msg.args?.index ?? 0);
+        break;
+      case "queue_remove":
+        h.queueRemove?.(msg.args?.index ?? 0);
+        break;
+      case "enqueue": {
+        const a = msg.args ?? {};
+        h.enqueue?.({
+          tracks: (a.tracks ?? []).map(descriptorToItem),
+          mode: a.mode ?? "now",
+          shuffle: !!a.shuffle,
+          startIndex: a.startIndex ?? 0
+        });
+        break;
+      }
+      default:
+        this.debug("unknown command", msg.action);
+    }
+  }
+  resync() {
+    if (this.lastTrack)
+      this.setNowPlaying(this.lastTrack);
+    if (this.lastStatus !== null) {
+      this.send({
+        type: "message",
+        device_id: this.deviceId,
+        token: this.getToken(),
+        data: { type: "status", status: this.lastStatus }
+      });
+    }
+    if (this.lastQueue)
+      this.setQueue(this.lastQueue.items, this.lastQueue.index);
+  }
+}
+function descriptorToItem(d) {
+  return {
+    uploadId: d.uploadId,
+    trackId: d.trackId,
+    title: d.title ?? "",
+    artist: d.artist ?? "",
+    album: d.album,
+    albumArtist: d.album_artist,
+    albumArt: d.album_art,
+    durationMs: d.duration,
+    songUri: d.song_uri,
+    albumUri: d.album_uri,
+    trackNumber: d.track_number
+  };
+}
+// src/remote-controller.ts
+class RemoteController {
+  opts;
+  ws = null;
+  stopped = false;
+  heartbeat;
+  reconnectTimer;
+  url;
+  heartbeatMs;
+  reconnectMs;
+  getToken;
+  debug;
+  handlers = {};
+  constructor(opts) {
+    this.opts = opts;
+    this.url = opts.url ?? DEFAULT_REMOTE_WS;
+    this.heartbeatMs = opts.heartbeatMs ?? 1e4;
+    this.reconnectMs = opts.reconnectMs ?? 3000;
+    this.getToken = typeof opts.token === "function" ? opts.token : () => opts.token;
+    this.debug = opts.debug ?? (() => {});
+  }
+  on(event, handler) {
+    this.handlers[event] = handler;
+    return this;
+  }
+  connect() {
+    this.stopped = false;
+    this.open();
+  }
+  disconnect() {
+    this.stopped = true;
+    if (this.reconnectTimer)
+      clearTimeout(this.reconnectTimer);
+    if (this.heartbeat)
+      clearInterval(this.heartbeat);
+    try {
+      this.ws?.close();
+    } catch {}
+    this.ws = null;
+  }
+  setPrimary(deviceId) {
+    this.send({ type: "set_primary", device_id: deviceId, token: this.getToken() });
+  }
+  play(target) {
+    this.command("play", target);
+  }
+  pause(target) {
+    this.command("pause", target);
+  }
+  next(target) {
+    this.command("next", target);
+  }
+  previous(target) {
+    this.command("previous", target);
+  }
+  seek(target, positionMs) {
+    this.command("seek", target, { position: positionMs });
+  }
+  queueJump(target, index) {
+    this.command("queue_jump", target, { index });
+  }
+  queueRemove(target, index) {
+    this.command("queue_remove", target, { index });
+  }
+  enqueue(target, tracks, mode = "now", shuffle = false, startIndex = 0) {
+    this.command("enqueue", target, {
+      tracks: tracks.map((t) => ({
+        uploadId: t.uploadId,
+        trackId: t.trackId,
+        title: t.title,
+        artist: t.artist,
+        album: t.album,
+        album_artist: t.albumArtist,
+        album_art: t.albumArt,
+        duration: t.durationMs,
+        song_uri: t.songUri,
+        album_uri: t.albumUri,
+        track_number: t.trackNumber
+      })),
+      mode,
+      shuffle,
+      startIndex
+    });
+  }
+  command(action, target, args) {
+    const payload = { type: "command", action, token: this.getToken() };
+    if (target)
+      payload.target = target;
+    if (args !== undefined)
+      payload.args = args;
+    this.send(payload);
+  }
+  send(payload) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      try {
+        this.ws.send(JSON.stringify(payload));
+      } catch (e) {
+        this.debug("send error", e);
+      }
+    }
+  }
+  open() {
+    if (this.stopped)
+      return;
+    const token = this.getToken();
+    if (!token) {
+      this.reconnectTimer = setTimeout(() => this.open(), this.reconnectMs);
+      return;
+    }
+    let ws;
+    try {
+      ws = new WebSocket(this.url);
+    } catch (e) {
+      this.debug("connect failed", e);
+      this.reconnectTimer = setTimeout(() => this.open(), this.reconnectMs);
+      return;
+    }
+    this.ws = ws;
+    ws.onopen = () => {
+      this.debug("connected");
+      this.send({ type: "register", clientName: this.opts.name, token: this.getToken() });
+      if (this.heartbeat)
+        clearInterval(this.heartbeat);
+      this.heartbeat = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN)
+          ws.send("ping");
+      }, this.heartbeatMs);
+    };
+    ws.onmessage = (ev) => {
+      if (ev.data === "pong")
+        return;
+      let msg;
+      try {
+        msg = JSON.parse(ev.data);
+      } catch {
+        return;
+      }
+      this.handle(msg);
+    };
+    ws.onerror = () => {
+      try {
+        ws.close();
+      } catch {}
+    };
+    ws.onclose = () => {
+      this.debug("disconnected");
+      if (this.heartbeat)
+        clearInterval(this.heartbeat);
+      if (this.ws === ws)
+        this.ws = null;
+      if (!this.stopped) {
+        if (this.reconnectTimer)
+          clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = setTimeout(() => this.open(), this.reconnectMs);
+      }
+    };
+  }
+  handle(msg) {
+    if (msg.status === "registered")
+      return;
+    switch (msg.type) {
+      case "devices":
+        this.handlers.devices?.({
+          primaryDevice: msg.primary_device ?? null,
+          devices: (msg.devices ?? []).map(deviceFromJson)
+        });
+        break;
+      case "device_registered":
+        this.handlers.deviceRegistered?.({
+          deviceId: msg.deviceId ?? "",
+          name: msg.clientName ?? ""
+        });
+        break;
+      case "device_unregistered":
+        this.handlers.deviceUnregistered?.({ deviceId: msg.device_id ?? "" });
+        break;
+      case "primary_changed":
+        this.handlers.primaryChanged?.({ deviceId: msg.device_id ?? "" });
+        break;
+      case "message":
+        this.handleMessage(msg);
+        break;
+      default:
+        this.debug("unknown frame", msg.type);
+    }
+  }
+  handleMessage(msg) {
+    const deviceId = msg.device_id ?? "";
+    const deviceName = msg.device_name ?? "";
+    const data = msg.data;
+    if (!data)
+      return;
+    switch (data.type) {
+      case "track":
+        this.handlers.nowPlaying?.({ deviceId, deviceName, track: trackFromJson(data) });
+        break;
+      case "status":
+        this.handlers.status?.({ deviceId, deviceName, status: statusFromCode(data.status) });
+        break;
+      case "queue":
+        this.handlers.queue?.({
+          deviceId,
+          deviceName,
+          index: data.index ?? 0,
+          queue: (data.queue ?? []).map(queueItemFromJson)
+        });
+        break;
+    }
+  }
+}
+function statusFromCode(code) {
+  return code === 1 ? "playing" : code === 0 ? "stopped" : "paused";
+}
+function trackFromJson(d) {
+  return {
+    title: d.title ?? "",
+    artist: d.artist ?? "",
+    album: d.album,
+    albumArtist: d.album_artist,
+    albumArt: d.album_art,
+    durationMs: d.duration_ms ?? d.length,
+    elapsedMs: d.elapsed,
+    isPlaying: d.is_playing,
+    songUri: d.song_uri,
+    albumUri: d.album_uri,
+    artistUri: d.artist_uri,
+    sha256: d.sha256,
+    liked: d.liked
+  };
+}
+function queueItemFromJson(d) {
+  return {
+    uploadId: d.uploadId,
+    trackId: d.trackId,
+    title: d.title ?? "",
+    artist: d.artist ?? "",
+    album: d.album,
+    albumArtist: d.album_artist,
+    albumArt: d.album_art,
+    durationMs: d.duration,
+    songUri: d.song_uri,
+    albumUri: d.album_uri,
+    trackNumber: d.track_number
+  };
+}
+function deviceFromJson(d) {
+  return {
+    deviceId: d.device_id ?? "",
+    name: d.name ?? "",
+    nowPlaying: d.now_playing ? trackFromJson(d.now_playing) : undefined,
+    queueIndex: d.queue?.index ?? 0,
+    queue: (d.queue?.queue ?? []).map(queueItemFromJson)
+  };
+}
+export {
+  RemotePlayer,
+  RemoteController,
+  DEFAULT_REMOTE_WS
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocksky/sdk",
-  "version": "0.10.1",
+  "version": "0.11.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": {
@@ -21,6 +21,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./remote": {
+      "types": "./dist/remote.d.ts",
+      "import": "./dist/remote.js",
+      "default": "./dist/remote.js"
     }
   },
   "files": [
@@ -29,7 +34,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm --packages external && bun run build:types",
+    "build": "bun build ./src/index.ts ./src/remote.ts --outdir ./dist --target node --format esm --packages external && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "bun test",

package/src/agent.ratelimit.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, test } from "bun:test";
+
+import { Agent, MAX_SAFE_WRITES_PER_HOUR, DEFAULT_MATCH_SONG_PER_HOUR } from "./agent.js";
+
+/**
+ * A fake XRPC client that counts writes and records the wall-clock time of each
+ * one, without ever touching a PDS. Nothing here talks to the network.
+ */
+function fakeAgent(pds: string): {
+  agent: Agent;
+  writeTimes: number[];
+} {
+  const writeTimes: number[] = [];
+  let n = 0;
+  const rpc = {
+    async post(nsid: string, opts: { input: { collection: string } }) {
+      if (
+        nsid === "com.atproto.repo.createRecord" ||
+        nsid === "com.atproto.repo.putRecord" ||
+        nsid === "com.atproto.repo.deleteRecord"
+      ) {
+        writeTimes.push(Date.now());
+        return { ok: true, data: { uri: `at://did:plc:test/${opts.input.collection}/rec${++n}` } };
+      }
+      return { ok: false, data: { error: "UnexpectedCall", message: nsid } };
+    },
+  };
+  // The constructor is private (compile-time only); bun runs the source
+  // directly, so we can instantiate with a stub client + no real session.
+  const agent = new (Agent as unknown as new (...a: unknown[]) => Agent)(rpc, "did:plc:test", {}, pds);
+  return { agent, writeTimes };
+}
+
+const OFFICIAL = "https://amanita.us-east.host.bsky.network";
+const SELFHOSTED = "https://pds.example.com";
+
+describe("Agent PDS identity", () => {
+  test("recognizes the official Bluesky PDS by *.bsky.network host", () => {
+    expect(fakeAgent(OFFICIAL).agent.isOfficialBlueskyPds).toBe(true);
+    expect(fakeAgent("https://bsky.network").agent.isOfficialBlueskyPds).toBe(true);
+    expect(fakeAgent("https://Puffball.US-West.HOST.BSKY.NETWORK").agent.isOfficialBlueskyPds).toBe(true);
+  });
+
+  test("a self-hosted PDS is not treated as official", () => {
+    expect(fakeAgent(SELFHOSTED).agent.isOfficialBlueskyPds).toBe(false);
+    // A look-alike host that only *contains* the string must not match.
+    expect(fakeAgent("https://not-bsky.network.evil.com").agent.isOfficialBlueskyPds).toBe(false);
+    expect(fakeAgent("https://bsky.network.evil.com").agent.isOfficialBlueskyPds).toBe(false);
+  });
+
+  test("exposes the resolved PDS host", () => {
+    expect(fakeAgent(SELFHOSTED).agent.pdsHost).toBe("pds.example.com");
+  });
+});
+
+describe("configureRateLimit policy (guard is authoritative)", () => {
+  test("self-hosted: disabling turns the throttle fully off", () => {
+    const { agent } = fakeAgent(SELFHOSTED);
+    const state = agent.configureRateLimit({ disabled: true });
+    expect(state.enabled).toBe(false);
+    expect(state.forcedOn).toBe(false);
+    expect(state.writesPerHour).toBe(Infinity);
+  });
+
+  test("official Bluesky: disabling is IGNORED — throttle forced back on at the safe rate", () => {
+    const { agent } = fakeAgent(OFFICIAL);
+    const state = agent.configureRateLimit({ disabled: true });
+    expect(state.enabled).toBe(true);
+    expect(state.forcedOn).toBe(true);
+    expect(state.writesPerHour).toBe(MAX_SAFE_WRITES_PER_HOUR);
+  });
+
+  test("official Bluesky: a huge writesPerHour is clamped to the safe ceiling", () => {
+    const { agent } = fakeAgent(OFFICIAL);
+    const state = agent.configureRateLimit({ writesPerHour: 1_000_000 });
+    expect(state.enabled).toBe(true);
+    expect(state.capped).toBe(true);
+    expect(state.writesPerHour).toBe(MAX_SAFE_WRITES_PER_HOUR);
+  });
+
+  test("official Bluesky: even disabled+huge can never exceed the points budget", () => {
+    const { agent } = fakeAgent(OFFICIAL);
+    const state = agent.configureRateLimit({ disabled: true, writesPerHour: 1_000_000 });
+    expect(state.writesPerHour).toBe(MAX_SAFE_WRITES_PER_HOUR);
+    // Sanity: the effective rate stays inside Bluesky's ~5000 points/hour budget.
+    expect(state.writesPerHour * 3).toBeLessThanOrEqual(5000);
+  });
+
+  test("self-hosted: a custom writesPerHour above the Bluesky ceiling is honored, not clamped", () => {
+    const { agent } = fakeAgent(SELFHOSTED);
+    const state = agent.configureRateLimit({ writesPerHour: 1_000_000 });
+    expect(state.enabled).toBe(true);
+    expect(state.capped).toBe(false);
+    expect(state.writesPerHour).toBe(1_000_000);
+  });
+
+  test("default (no options) enables the throttle at the safe rate on any PDS", () => {
+    expect(fakeAgent(SELFHOSTED).agent.configureRateLimit().writesPerHour).toBe(MAX_SAFE_WRITES_PER_HOUR);
+    expect(fakeAgent(OFFICIAL).agent.configureRateLimit().writesPerHour).toBe(MAX_SAFE_WRITES_PER_HOUR);
+  });
+
+  test("a zero / NaN writesPerHour falls back to the safe rate, never 'unlimited'", () => {
+    const { agent } = fakeAgent(SELFHOSTED);
+    expect(agent.configureRateLimit({ writesPerHour: 0 }).writesPerHour).toBe(MAX_SAFE_WRITES_PER_HOUR);
+    expect(agent.configureRateLimit({ writesPerHour: NaN }).writesPerHour).toBe(MAX_SAFE_WRITES_PER_HOUR);
+    expect(agent.configureRateLimit({ writesPerHour: -5 }).writesPerHour).toBe(MAX_SAFE_WRITES_PER_HOUR);
+  });
+});
+
+describe("matchSong AppView throttle is ALWAYS enforced", () => {
+  test("default matchSong rate is derived from the AppView's per-IP budget", () => {
+    // 1000 req / 30s * 0.9 * 3600 = 108,000/h — and never exceeds the raw budget.
+    expect(DEFAULT_MATCH_SONG_PER_HOUR).toBe(108_000);
+    expect(DEFAULT_MATCH_SONG_PER_HOUR / 3600).toBeLessThanOrEqual((1000 / 30));
+    expect(fakeAgent(SELFHOSTED).agent.configureRateLimit().matchSongPerHour).toBe(DEFAULT_MATCH_SONG_PER_HOUR);
+  });
+
+  test("disabling the write throttle does NOT disable matchSong (self-hosted)", () => {
+    const { agent } = fakeAgent(SELFHOSTED);
+    const state = agent.configureRateLimit({ disabled: true });
+    expect(state.enabled).toBe(false); // writes off
+    expect(state.matchSongPerHour).toBe(DEFAULT_MATCH_SONG_PER_HOUR); // matchSong still on
+  });
+
+  test("matchSongPerHour can be retuned and persists across calls", () => {
+    const { agent } = fakeAgent(SELFHOSTED);
+    expect(agent.configureRateLimit({ matchSongPerHour: 500 }).matchSongPerHour).toBe(500);
+    // A later call that doesn't mention matchSong keeps the tuned value.
+    expect(agent.configureRateLimit({ disabled: true }).matchSongPerHour).toBe(500);
+    // Non-positive values are ignored (never turns matchSong off).
+    expect(agent.configureRateLimit({ matchSongPerHour: 0 }).matchSongPerHour).toBe(500);
+    expect(agent.configureRateLimit({ matchSongPerHour: -1 }).matchSongPerHour).toBe(500);
+  });
+});
+
+describe("throttle behavior (observable, no real PDS)", () => {
+  test("by default there is no throttle — a burst of writes runs back-to-back", async () => {
+    const { agent, writeTimes } = fakeAgent(SELFHOSTED);
+    for (let i = 0; i < 5; i++) await agent.createArtist({ name: `Artist ${i}` });
+    expect(writeTimes).toHaveLength(5);
+    // No configured limit → the whole burst completes near-instantly.
+    expect(writeTimes.at(-1)! - writeTimes[0]!).toBeLessThan(50);
+  });
+
+  test("when enabled, writes are spaced at least the configured interval apart", async () => {
+    const { agent, writeTimes } = fakeAgent(SELFHOSTED);
+    // 180k writes/hour → 20ms minimum spacing; keeps the test fast but measurable.
+    agent.configureRateLimit({ writesPerHour: 180_000 });
+    const N = 4;
+    for (let i = 0; i < N; i++) await agent.createArtist({ name: `Artist ${i}` });
+    expect(writeTimes).toHaveLength(N);
+    // (N-1) gaps of ~20ms each; allow slack for timer jitter but require real spacing.
+    const elapsed = writeTimes.at(-1)! - writeTimes[0]!;
+    expect(elapsed).toBeGreaterThanOrEqual((N - 1) * 20 * 0.8);
+  });
+
+  test("disabling after enabling removes the spacing again (self-hosted)", async () => {
+    const { agent, writeTimes } = fakeAgent(SELFHOSTED);
+    agent.configureRateLimit({ writesPerHour: 180_000 });
+    agent.configureRateLimit({ disabled: true });
+    for (let i = 0; i < 5; i++) await agent.createArtist({ name: `Artist ${i}` });
+    expect(writeTimes.at(-1)! - writeTimes[0]!).toBeLessThan(50);
+  });
+});

package/src/agent.ts

@@ -50,6 +50,120 @@ function nowISO(): string {
   return new Date().toISOString();
 }
 
+/** Lower-case hostname of a URL, or "" if it can't be parsed. */
+function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+// --- PDS write-rate limiting -----------------------------------------------
+// Bluesky's PDS rate-limits repo writes by *points*, not requests: ~5,000
+// points/hour per account, and each createRecord/putRecord/deleteRecord costs
+// ~3 points. A bulk operation (importing a listening history) would blow that
+// budget in seconds, so the Agent can throttle its own writes to stay inside
+// it. The gate is OFF by default — single live scrobbles never need it — and
+// callers opt in via {@link Agent.configureRateLimit}.
+const PDS_WRITE_POINT_BUDGET_PER_HOUR = 5_000;
+const POINTS_PER_WRITE = 3;
+const SAFETY_MARGIN = 0.9; // headroom for 429 retries / clock skew
+
+/**
+ * The highest sustained writes-per-hour that still fits Bluesky's write-point
+ * budget. On the official Bluesky PDS this is a hard ceiling the Agent will not
+ * let any caller exceed; self-hosted PDSes may allow more (or none).
+ */
+export const MAX_SAFE_WRITES_PER_HOUR = Math.floor(
+  (PDS_WRITE_POINT_BUDGET_PER_HOUR * SAFETY_MARGIN) / POINTS_PER_WRITE,
+);
+
+// Rocksky's AppView `matchSong` endpoint is a *shared* service, and unlike PDS
+// writes its rate limit is NOT the account owner's to waive — running your own
+// PDS grants no extra AppView capacity. So matchSong is ALWAYS throttled,
+// independent of the write throttle and of any `disabled` request.
+//
+// The AppView applies a global per-IP XRPC limit (see apps/api/src/index.ts:
+// 1000 requests / 30s). matchSong runs against exactly that budget, so we throttle
+// it to a safe fraction of the real server limit. Tune via `matchSongPerHour` if
+// you operate your own AppView with a different limit.
+const APPVIEW_REQUEST_LIMIT = 1_000; // requests …
+const APPVIEW_WINDOW_SECONDS = 30; // … per this window (apps/api global rate limiter)
+export const DEFAULT_MATCH_SONG_PER_HOUR = Math.floor(
+  ((APPVIEW_REQUEST_LIMIT * SAFETY_MARGIN) / APPVIEW_WINDOW_SECONDS) * 3_600,
+); // ≈ 108,000/h (~30 req/s) — 90% of the AppView's per-IP budget
+
+/** Options for {@link Agent.configureRateLimit}. */
+export interface RateLimitOptions {
+  /**
+   * Target writes (createRecord/putRecord/deleteRecord) per hour. Omitted →
+   * {@link MAX_SAFE_WRITES_PER_HOUR}. On the official Bluesky PDS this is
+   * clamped to the safe ceiling; on a self-hosted PDS it is honored as given.
+   * Ignored when `disabled` is true.
+   */
+  writesPerHour?: number;
+  /**
+   * Turn the client-side *write* throttle off entirely. Honored on self-hosted
+   * PDSes (useful when you run your own PDS with its own limits). IGNORED —
+   * forced back on at the safe rate — when the account lives on the official
+   * Bluesky PDS (*.bsky.network), whose budget is enforced server-side.
+   *
+   * NOTE: this never affects the Rocksky AppView `matchSong` throttle, which is
+   * always enforced (see {@link RateLimitOptions.matchSongPerHour}).
+   */
+  disabled?: boolean;
+  /**
+   * Target Rocksky AppView `matchSong` calls per hour. ALWAYS enforced — a
+   * self-hosted PDS grants no extra AppView capacity — so `disabled` never turns
+   * it off; this only tunes the rate. Omitted → keep the current value
+   * (default {@link DEFAULT_MATCH_SONG_PER_HOUR}). Non-positive values are ignored.
+   */
+  matchSongPerHour?: number;
+}
+
+/** The effective throttle state after {@link Agent.configureRateLimit} applies policy. */
+export interface RateLimitState {
+  /** Whether the *write* throttle is active. */
+  enabled: boolean;
+  /** Effective writes/hour cap (Infinity when disabled). */
+  writesPerHour: number;
+  /** True when `disabled` was requested but overridden by the bsky.network guard. */
+  forcedOn: boolean;
+  /** True when a requested `writesPerHour` was clamped to the safe ceiling. */
+  capped: boolean;
+  /** The resolved PDS host the decision was based on. */
+  pdsHost: string;
+  /** Effective Rocksky AppView matchSong rate — always enforced, never disabled. */
+  matchSongPerHour: number;
+}
+
+/**
+ * Global throttle: spaces calls at least `minIntervalMs` apart. A single shared
+ * `nextAt` cursor is advanced atomically per {@link RateGate.take}, so even
+ * highly concurrent callers never burst past the configured rate.
+ * `minIntervalMs <= 0` means no throttle (take() resolves immediately).
+ */
+class RateGate {
+  private nextAt = 0;
+  private minIntervalMs = 0;
+
+  /** null / non-positive → no throttle. */
+  setRate(writesPerHour: number | null): void {
+    this.minIntervalMs =
+      writesPerHour && writesPerHour > 0 ? Math.ceil(3_600_000 / writesPerHour) : 0;
+  }
+
+  async take(): Promise<void> {
+    if (this.minIntervalMs <= 0) return;
+    const now = Date.now();
+    const at = Math.max(now, this.nextAt);
+    this.nextAt = at + this.minIntervalMs;
+    const delay = at - now;
+    if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+  }
+}
+
 // 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 };
@@ -80,13 +194,88 @@ export type ArtistInput = Omit<ArtistRecord, "createdAt"> & { createdAt?: string
  */
 export class Agent {
   private idx?: RockskyIndex;
+  // PDS write throttle — off by default: single live scrobbles don't need it. An
+  // import (or any bulk writer) opts in via configureRateLimit().
+  private writeGate = new RateGate();
+  // Rocksky AppView matchSong throttle — ALWAYS on. A self-hosted PDS grants no
+  // extra AppView capacity, so this is never disabled, only tuned.
+  private matchGate = new RateGate();
+  private matchSongPerHour = DEFAULT_MATCH_SONG_PER_HOUR;
+
+  /** Lower-case hostname of the account's resolved PDS (e.g. "pds.example.com"). */
+  readonly pdsHost: string;
 
   private constructor(
     private rpc: Client,
     readonly did: string,
     readonly session: PasswordSession,
     private pds: string,
-  ) {}
+  ) {
+    this.pdsHost = hostOf(pds);
+    this.matchGate.setRate(this.matchSongPerHour);
+  }
+
+  /**
+   * Whether the account lives on the official Bluesky PDS (*.bsky.network).
+   * Its write budget is enforced server-side, so the client-side throttle can
+   * never be disabled for these hosts.
+   */
+  get isOfficialBlueskyPds(): boolean {
+    return this.pdsHost === "bsky.network" || this.pdsHost.endsWith(".bsky.network");
+  }
+
+  /**
+   * Configure the client-side write throttle and return the effective state.
+   *
+   * Policy — the *.bsky.network guard is authoritative and cannot be bypassed:
+   *  - `disabled: true` turns the throttle off on a self-hosted PDS, but on the
+   *    official Bluesky PDS it is ignored and the throttle stays on at the safe
+   *    rate (`forcedOn: true`).
+   *  - `writesPerHour` is honored as given on a self-hosted PDS, but clamped to
+   *    {@link MAX_SAFE_WRITES_PER_HOUR} on the official Bluesky PDS
+   *    (`capped: true` when clamped).
+   *  - Omitting both enables the throttle at the safe default rate.
+   */
+  configureRateLimit(opts: RateLimitOptions = {}): RateLimitState {
+    // matchSong throttle is always enforced — `disabled` never touches it. A
+    // positive `matchSongPerHour` retunes it; anything else keeps the current rate.
+    if (opts.matchSongPerHour !== undefined && opts.matchSongPerHour > 0) {
+      this.matchSongPerHour = opts.matchSongPerHour;
+      this.matchGate.setRate(this.matchSongPerHour);
+    }
+
+    const official = this.isOfficialBlueskyPds;
+    const state = (partial: Omit<RateLimitState, "pdsHost" | "matchSongPerHour">): RateLimitState => ({
+      ...partial,
+      pdsHost: this.pdsHost,
+      matchSongPerHour: this.matchSongPerHour,
+    });
+
+    if (opts.disabled) {
+      if (official) {
+        // Guard: never let the write throttle be turned off on the official
+        // Bluesky PDS — that only earns 429s and risks account-level throttling.
+        const writesPerHour = Math.min(
+          opts.writesPerHour ?? MAX_SAFE_WRITES_PER_HOUR,
+          MAX_SAFE_WRITES_PER_HOUR,
+        );
+        this.writeGate.setRate(writesPerHour);
+        return state({ enabled: true, writesPerHour, forcedOn: true, capped: false });
+      }
+      this.writeGate.setRate(null);
+      return state({ enabled: false, writesPerHour: Infinity, forcedOn: false, capped: false });
+    }
+
+    let writesPerHour = opts.writesPerHour ?? MAX_SAFE_WRITES_PER_HOUR;
+    if (!(writesPerHour > 0)) writesPerHour = MAX_SAFE_WRITES_PER_HOUR; // reject 0 / NaN / negatives
+    let capped = false;
+    if (official && writesPerHour > MAX_SAFE_WRITES_PER_HOUR) {
+      writesPerHour = MAX_SAFE_WRITES_PER_HOUR;
+      capped = true;
+    }
+    this.writeGate.setRate(writesPerHour);
+    return state({ enabled: true, writesPerHour, forcedOn: false, capped });
+  }
 
   /**
    * Resolve the account's PDS, authenticate with an app password, and return an
@@ -132,6 +321,7 @@ export class Agent {
   }
 
   private async create(collection: string, record: Record<string, unknown>): Promise<string> {
+    await this.writeGate.take();
     const res = await this.rpc.post("com.atproto.repo.createRecord" as never, {
       input: { repo: this.did, collection, record: { ...record, $type: collection } },
     } as never);
@@ -140,6 +330,7 @@ export class Agent {
   }
 
   private async putRecord(collection: string, rkey: string, record: Record<string, unknown>): Promise<string> {
+    await this.writeGate.take();
     const res = await this.rpc.post("com.atproto.repo.putRecord" as never, {
       input: { repo: this.did, collection, rkey, record: { ...record, $type: collection } },
     } as never);
@@ -149,6 +340,7 @@ export class Agent {
 
   /** Delete a record by collection + rkey. */
   async delete(collection: string, rkey: string): Promise<void> {
+    await this.writeGate.take();
     const res = await this.rpc.post("com.atproto.repo.deleteRecord" as never, {
       input: { repo: this.did, collection, rkey },
     } as never);
@@ -223,6 +415,9 @@ export class Agent {
   async scrobbleMatch(input: ScrobbleMatchInput, appview?: string): Promise<string> {
     const { title, artist, album, mbId, isrc, timestamp } = input;
     const { RockskyClient } = await import("./client.js");
+    // matchSong hits the shared Rocksky AppView; always throttle it, regardless
+    // of the write-throttle policy (a self-hosted PDS grants no AppView capacity).
+    await this.matchGate.take();
     const m = (await new RockskyClient(appview).matchSong(title, artist, mbId, isrc)) as Record<
       string,
       unknown

package/src/index.ts

@@ -13,11 +13,15 @@ export type { DateInterval } from "./client.js";
 export { RockskyLibrary } from "./library.js";
 export {
   Agent,
+  MAX_SAFE_WRITES_PER_HOUR,
+  DEFAULT_MATCH_SONG_PER_HOUR,
   type ScrobbleInput,
   type ScrobbleMatchInput,
   type SongInput,
   type AlbumInput,
   type ArtistInput,
+  type RateLimitOptions,
+  type RateLimitState,
 } from "./agent.js";
 export { RockskyIndex, totalIndexed, type IndexStats } from "./dedup.js";
 export { runJetstream, DEFAULT_JETSTREAM_SERVERS, type JetstreamOptions } from "./jetstream.js";

package/src/remote.ts

@@ -0,0 +1,23 @@
+// Browser-safe entry: the remote-control player + controller only.
+//
+// The main entry (`@rocksky/sdk`) bundles the dedup index (classic-level) and
+// the identity hashes (node:crypto), which are Node-only. The remote player /
+// controller are pure WebSocket + JSON with zero Node dependencies, so this
+// subpath (`@rocksky/sdk/remote`) is safe to import from a browser bundle.
+
+export {
+  RemotePlayer,
+  DEFAULT_REMOTE_WS,
+  type RemotePlayerOptions,
+  type RemotePlayerHandlers,
+  type RemoteNowPlaying,
+  type RemoteQueueItem,
+  type EnqueueCommand,
+} from "./remote-player.js";
+export {
+  RemoteController,
+  type RemoteControllerOptions,
+  type RemoteControllerEvents,
+  type RemoteDevice,
+  type RemoteStatus,
+} from "./remote-controller.js";