@rocksky/sdk 0.1.0

package/dist/paginate.d.ts

@@ -0,0 +1,38 @@
+export type PageOpts = {
+    limit: number;
+    offset: number;
+    cursor?: string;
+};
+export type PageResult<T> = {
+    items: T[];
+    cursor?: string;
+};
+export type PaginateArgs<T> = {
+    /**
+     * Fetch one page. Return either:
+     *   - an array of items (offset/limit mode — pagination stops when an empty
+     *     page or a short page comes back), or
+     *   - a `{ items, cursor }` object (cursor mode — pagination stops when
+     *     `cursor` is missing/null).
+     */
+    fetch: (opts: PageOpts) => Promise<PageResult<T> | T[]>;
+    pageSize?: number;
+    maxItems?: number;
+    signal?: AbortSignal;
+};
+/**
+ * Page through an XRPC endpoint as an async iterable.
+ *
+ *   for await (const s of paginate({
+ *     fetch: ({ limit, offset }) =>
+ *       client.actor.getActorScrobbles({ did, limit, offset }),
+ *     pageSize: 50,
+ *   })) {
+ *     console.log(s.track.title);
+ *   }
+ */
+export declare function paginate<T>(args: PaginateArgs<T>): AsyncIterable<T> & {
+    /** Collect every item into an array — convenience for small result sets. */
+    toArray(): Promise<T[]>;
+};
+//# sourceMappingURL=paginate.d.ts.map

package/dist/paginate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../src/paginate.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAC1B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC5B;;;;;;OAMG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG;IACrE,4EAA4E;IAC5E,OAAO,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACzB,CAqCA"}

package/dist/pipe.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Compose async operators.
+ *
+ *   const handle = await pipe(
+ *     () => client.actor.getProfile({ did }),  // thunk — withRetry can re-invoke
+ *     withRetry(3),
+ *     withTimeout(5_000),
+ *     tap(p => console.log("got", p.handle)),
+ *     map(p => p.handle.toUpperCase()),
+ *   );
+ *
+ * `pipe` accepts either a thunk `() => Promise<T>` or a bare `Promise<T>`.
+ * Operators take a factory so they can re-invoke the upstream chain (for
+ * retry). If you pass a bare Promise, the work has already started and
+ * `withRetry` becomes a no-op — pass a thunk if you want true retries.
+ */
+export type Op<A, B> = (factory: () => Promise<A>) => () => Promise<B>;
+type Source<A> = Promise<A> | (() => Promise<A>);
+export declare function pipe<A>(value: Source<A>): Promise<A>;
+export declare function pipe<A, B>(value: Source<A>, op1: Op<A, B>): Promise<B>;
+export declare function pipe<A, B, C>(value: Source<A>, op1: Op<A, B>, op2: Op<B, C>): Promise<C>;
+export declare function pipe<A, B, C, D>(value: Source<A>, op1: Op<A, B>, op2: Op<B, C>, op3: Op<C, D>): Promise<D>;
+export declare function pipe<A, B, C, D, E>(value: Source<A>, op1: Op<A, B>, op2: Op<B, C>, op3: Op<C, D>, op4: Op<D, E>): Promise<E>;
+export declare function pipe<A, B, C, D, E, F>(value: Source<A>, op1: Op<A, B>, op2: Op<B, C>, op3: Op<C, D>, op4: Op<D, E>, op5: Op<E, F>): Promise<F>;
+export declare function map<A, B>(fn: (a: A) => B | Promise<B>): Op<A, B>;
+export declare function tap<A>(fn: (a: A) => unknown | Promise<unknown>): Op<A, A>;
+export declare function withRetry<A>(times: number, options?: {
+    delayMs?: number;
+    factor?: number;
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+}): Op<A, A>;
+export declare function withTimeout<A>(ms: number): Op<A, A>;
+export declare function withFallback<A>(fallback: A | ((err: unknown) => A | Promise<A>)): Op<A, A>;
+export declare function catchError<A, B>(handler: (err: unknown) => B | Promise<B>): Op<A, A | B>;
+export {};
+//# sourceMappingURL=pipe.d.ts.map

package/dist/pipe.d.ts.map

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

package/dist/realtime.d.ts

@@ -0,0 +1,144 @@
+/** Minimal WebSocket interface — works with browser `WebSocket`, `ws`, `bun`. */
+export interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "close", listener: (event: {
+        code: number;
+        reason: string;
+    }) => void): void;
+    addEventListener(type: "error", listener: (event: unknown) => void): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: string, listener: (event: unknown) => void): void;
+}
+export type WebSocketCtor = new (url: string) => WebSocketLike;
+export type ReconnectOptions = {
+    backoffMs?: number;
+    maxBackoffMs?: number;
+    maxAttempts?: number;
+    factor?: number;
+};
+export type RealtimeOptions = {
+    /** Full WebSocket URL — defaults to ws(s)://api.rocksky.app/ws (derived from baseUrl). */
+    url?: string;
+    /** Used to derive the WS URL when `url` is not set. Default: DEFAULT_BASE_URL. */
+    baseUrl?: string;
+    /** JWT token required to register and send messages. */
+    token: string | (() => string | Promise<string>);
+    /** Display name advertised to the server when registering. */
+    clientName?: string;
+    /** Auto-register on connect. Default: true. */
+    autoRegister?: boolean;
+    /** Reconnect on close. Pass `false` to disable. Default: `{ backoffMs: 500, factor: 2, maxBackoffMs: 30000 }`. */
+    reconnect?: boolean | ReconnectOptions;
+    /** Send `ping` every N ms to keep the socket warm. Default: 25000. Pass 0 to disable. */
+    pingIntervalMs?: number;
+    /** WebSocket constructor — defaults to global `WebSocket`. Pass a fake for tests. */
+    webSocket?: WebSocketCtor;
+};
+export type RealtimeEventMap = {
+    open: void;
+    close: {
+        code: number;
+        reason: string;
+    };
+    error: unknown;
+    registered: {
+        deviceId: string;
+    };
+    deviceRegistered: {
+        deviceId: string;
+        clientName: string;
+    };
+    message: {
+        data: unknown;
+        device_id: string;
+    };
+    control: {
+        type: string;
+        action: string;
+        args?: unknown;
+    };
+    raw: unknown;
+};
+export type RealtimeEvent = keyof RealtimeEventMap;
+export declare class RealtimeClient {
+    private readonly options;
+    private ws?;
+    private listeners;
+    private reconnectAttempts;
+    private pingTimer?;
+    private closed;
+    private deviceId?;
+    private readonly url;
+    private readonly reconnectOpts;
+    private readonly WsCtor;
+    constructor(options: RealtimeOptions);
+    /** Currently registered device ID (set after the server confirms registration). */
+    get currentDeviceId(): string | undefined;
+    /** Whether the underlying socket is OPEN. */
+    get isOpen(): boolean;
+    on<E extends RealtimeEvent>(event: E, listener: (payload: RealtimeEventMap[E]) => void): () => void;
+    off<E extends RealtimeEvent>(event: E, listener: (payload: RealtimeEventMap[E]) => void): void;
+    private emit;
+    /** Open the socket. Resolves once the WebSocket reaches OPEN. */
+    connect(): Promise<void>;
+    /** Manually register this connection with the server. */
+    register(): Promise<void>;
+    /**
+     * Broadcast a data message to all of the user's connected devices. The
+     * server uses `data.type === "track"` for now-playing updates.
+     */
+    sendMessage(data: Record<string, unknown>): Promise<void>;
+    /** Send a control message to one or all devices. */
+    sendControl(args: {
+        type?: string;
+        target?: string;
+        action: string;
+        args?: unknown;
+    }): Promise<void>;
+    /** Send a heartbeat ping. Server responds with "pong". */
+    ping(): void;
+    /** Send a raw message — escape hatch for unsupported message shapes. */
+    sendRaw(payload: unknown): void;
+    /** Close the socket and disable reconnect. */
+    close(code?: number, reason?: string): Promise<void>;
+    private attachHandlers;
+    private dispatch;
+    private scheduleReconnect;
+    private startPing;
+    private stopPing;
+}
+export declare function createRealtimeClient(opts: RealtimeOptions): RealtimeClient;
+/**
+ * Fluent builder for the realtime client.
+ *
+ *   const rt = RealtimeClient.builder()
+ *     .baseUrl("https://api.rocksky.app")
+ *     .token(() => loadToken())
+ *     .clientName("my-app")
+ *     .pingInterval(20_000)
+ *     .reconnect({ backoffMs: 1000, maxBackoffMs: 60_000 })
+ *     .build();
+ *
+ *   await rt.connect();
+ */
+export declare class RealtimeClientBuilder {
+    private opts;
+    url(u: string): this;
+    baseUrl(u: string): this;
+    token(t: RealtimeOptions["token"]): this;
+    clientName(name: string): this;
+    autoRegister(value: boolean): this;
+    reconnect(value: boolean | ReconnectOptions): this;
+    pingInterval(ms: number): this;
+    webSocket(ctor: WebSocketCtor): this;
+    build(): RealtimeClient;
+}
+export declare namespace RealtimeClient {
+    function builder(): RealtimeClientBuilder;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

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

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type AuthProvider = string | (() => string | Promise<string>);
+export type ClientOptions = {
+    baseUrl?: string;
+    auth?: AuthProvider;
+    fetch?: FetchLike;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number;
+    userAgent?: string;
+};
+export type RequestOptions = {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    retries?: number;
+    auth?: AuthProvider | null;
+};
+export type Pagination = {
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+};
+export declare const DEFAULT_BASE_URL = "https://api.rocksky.app";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GACZ,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,IAAI,EAAE,GACN;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE5B,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,GAAG,GAAG,EACnB,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAErE,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,gBAAgB,4BAA4B,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@rocksky/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Rocksky XRPC API",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tsirysndr/rocksky.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://github.com/tsirysndr/rocksky/tree/main/sdk/typescript#readme",
+  "bugs": {
+    "url": "https://github.com/tsirysndr/rocksky/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "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"
+  },
+  "keywords": [
+    "rocksky",
+    "atproto",
+    "at-protocol",
+    "bluesky",
+    "xrpc",
+    "scrobble",
+    "scrobbling",
+    "music",
+    "lastfm",
+    "now-playing",
+    "sdk",
+    "typescript",
+    "client",
+    "api"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.6.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,235 @@
+import { buildConfig, type HttpClientConfig, xrpcCall } from "./http";
+import {
+  type PaginateArgs,
+  paginate as paginateFn,
+} from "./paginate";
+import {
+  RealtimeClient,
+  type RealtimeOptions,
+  createRealtimeClient,
+} from "./realtime";
+import { ActorNamespace } from "./namespaces/actor";
+import { AlbumNamespace } from "./namespaces/album";
+import { ApikeyNamespace } from "./namespaces/apikey";
+import { ArtistNamespace } from "./namespaces/artist";
+import { ChartsNamespace } from "./namespaces/charts";
+import { DropboxNamespace } from "./namespaces/dropbox";
+import { FeedNamespace } from "./namespaces/feed";
+import { GoogleDriveNamespace } from "./namespaces/googledrive";
+import { GraphNamespace } from "./namespaces/graph";
+import { LikeNamespace } from "./namespaces/like";
+import { MirrorNamespace } from "./namespaces/mirror";
+import { PlayerNamespace } from "./namespaces/player";
+import { PlaylistNamespace } from "./namespaces/playlist";
+import { ScrobbleNamespace } from "./namespaces/scrobble";
+import { ShoutNamespace } from "./namespaces/shout";
+import { SongNamespace } from "./namespaces/song";
+import { SpotifyNamespace } from "./namespaces/spotify";
+import { StatsNamespace } from "./namespaces/stats";
+import type { Call } from "./namespaces/_helpers";
+import type {
+  AuthProvider,
+  ClientOptions,
+  FetchLike,
+  RequestOptions,
+} from "./types";
+
+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;
+
+  constructor(options: ClientOptions = {}) {
+    this.config = buildConfig(options);
+    const call: Call = (nsid, method, opts) =>
+      xrpcCall(this.config, nsid, method, opts ?? {});
+
+    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 one-off authenticated copy without mutating this client. */
+  withAuth(auth: AuthProvider): RockskyClient {
+    return new RockskyClient({
+      ...this.optionsSnapshot(),
+      auth,
+    });
+  }
+
+  /** Build a copy with an overridden base URL. */
+  withBaseUrl(baseUrl: string): RockskyClient {
+    return new RockskyClient({
+      ...this.optionsSnapshot(),
+      baseUrl,
+    });
+  }
+
+  /**
+   * 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,
+    });
+  }
+
+  /**
+   * 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. */
+  xrpc<T = unknown>(
+    nsid: string,
+    method: "GET" | "POST" = "GET",
+    opts: {
+      params?: Record<string, unknown>;
+      body?: unknown;
+      requireAuth?: boolean;
+    } & RequestOptions = {},
+  ): Promise<T> {
+    return xrpcCall<T>(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;
+  }
+
+  headers(headers: Record<string, string>): this {
+    this.opts.headers = { ...this.opts.headers, ...headers };
+    return this;
+  }
+
+  userAgent(ua: string): this {
+    this.opts.userAgent = ua;
+    return this;
+  }
+
+  timeout(ms: number): this {
+    this.opts.timeoutMs = ms;
+    return this;
+  }
+
+  retries(n: number): this {
+    this.opts.retries = n;
+    return this;
+  }
+
+  retryDelay(ms: number): this {
+    this.opts.retryDelayMs = ms;
+    return this;
+  }
+
+  build(): RockskyClient {
+    return new RockskyClient(this.opts);
+  }
+}
+
+/** Convenience factory — equivalent to `new RockskyClient(options)`. */
+export function createClient(options: ClientOptions = {}): RockskyClient {
+  return new RockskyClient(options);
+}

package/src/errors.ts

@@ -0,0 +1,47 @@
+export class RockskyError extends Error {
+  readonly cause?: unknown;
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message);
+    this.name = "RockskyError";
+    this.cause = options?.cause;
+  }
+}
+
+export class RockskyHttpError extends RockskyError {
+  readonly status: number;
+  readonly statusText: string;
+  readonly url: string;
+  readonly body: unknown;
+
+  constructor(args: {
+    status: number;
+    statusText: string;
+    url: string;
+    body: unknown;
+    message?: string;
+  }) {
+    const message =
+      args.message ??
+      `Rocksky API ${args.status} ${args.statusText} at ${args.url}`;
+    super(message);
+    this.name = "RockskyHttpError";
+    this.status = args.status;
+    this.statusText = args.statusText;
+    this.url = args.url;
+    this.body = args.body;
+  }
+}
+
+export class RockskyTimeoutError extends RockskyError {
+  constructor(ms: number) {
+    super(`Rocksky request timed out after ${ms}ms`);
+    this.name = "RockskyTimeoutError";
+  }
+}
+
+export class RockskyAuthError extends RockskyError {
+  constructor(message = "Authentication required") {
+    super(message);
+    this.name = "RockskyAuthError";
+  }
+}