@rocksky/sdk 0.10.2 → 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":"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"}
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocksky/sdk",
-  "version": "0.10.2",
+  "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": {

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";