@ewanc26/atproto 0.2.10 → 0.2.11

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,GAAG,QAAQ,CAqB7E;AAED,eAAO,MAAM,kBAAkB,UAAsD,CAAC;AACtF,eAAO,MAAM,YAAY,UAA6C,CAAC;AAKvE,wBAAsB,eAAe,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,OAAO,KAAK,GACpB,OAAO,CAAC,gBAAgB,CAAC,CA8B3B;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqB3F;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAKxF;AAED,wBAAsB,YAAY,CAAC,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,WAAW,UAAQ,EACnB,OAAO,CAAC,EAAE,OAAO,KAAK,GACpB,OAAO,CAAC,CAAC,CAAC,CAkBZ;AAED,wBAAgB,WAAW,IAAI,IAAI,CAGlC"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAuBnD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,GAAG,QAAQ,CAqB7E;AAED,eAAO,MAAM,kBAAkB,UAAsD,CAAC;AACtF,eAAO,MAAM,YAAY,UAA6C,CAAC;AAKvE,wBAAsB,eAAe,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,OAAO,KAAK,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAiC3B;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwB3F;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAKxF;AAED,wBAAsB,YAAY,CAAC,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,WAAW,UAAQ,EACnB,OAAO,CAAC,EAAE,OAAO,KAAK,GACpB,OAAO,CAAC,CAAC,CAAC,CAkBZ;AAED,wBAAgB,WAAW,IAAI,IAAI,CAGlC"}

package/dist/agents.js

@@ -1,5 +1,19 @@
 import { AtpAgent } from '@atproto/api';
 import { cache } from './cache.js';
+/** Default timeout for individual AT Protocol XRPC calls (ms). */
+const XRPC_TIMEOUT = 8_000;
+/** Default timeout for identity resolution (ms). */
+const IDENTITY_TIMEOUT = 5_000;
+/**
+ * Wraps a promise with a timeout. Rejects with a TimeoutError if the promise
+ * doesn't settle within `ms` milliseconds.
+ */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
 export function createAgent(service, fetchFn) {
     const wrappedFetch = fetchFn
         ? async (url, init) => {
@@ -31,7 +45,7 @@ export async function resolveIdentity(did, fetchFn) {
     if (cached)
         return cached;
     const _fetch = fetchFn ?? globalThis.fetch;
-    const response = await _fetch(`https://slingshot.microcosm.blue/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${encodeURIComponent(did)}`);
+    const response = await withTimeout(_fetch(`https://slingshot.microcosm.blue/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${encodeURIComponent(did)}`), IDENTITY_TIMEOUT);
     if (!response.ok) {
         throw new Error(`Failed to resolve identifier via Slingshot: ${response.status} ${response.statusText}`);
     }
@@ -54,7 +68,7 @@ export async function getPublicAgent(did, fetchFn) {
         return resolvedAgent;
     try {
         try {
-            const response = await constellationAgent.getProfile({ actor: did });
+            const response = await withTimeout(constellationAgent.getProfile({ actor: did }), XRPC_TIMEOUT);
             if (response.success) {
                 resolvedAgent = constellationAgent;
                 return resolvedAgent;
@@ -88,7 +102,7 @@ export async function withFallback(did, operation, usePDSFirst = false, fetchFn)
     for (const getAgent of agents) {
         try {
             const agent = await getAgent();
-            return await operation(agent);
+            return await withTimeout(operation(agent), XRPC_TIMEOUT);
         }
         catch (error) {
             lastError = error;

package/dist/jetstream.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Jetstream WebSocket client for AT Protocol real-time event streaming.
+ *
+ * Jetstream is a simplified JSON event stream that converts the CBOR-encoded
+ * AT Protocol firehose into lightweight, friendly JSON objects.
+ *
+ * @see https://github.com/bluesky-social/jetstream
+ */
+import type { JetstreamOptions, JetstreamEventHandler, JetstreamErrorHandler, JetstreamConnectionState } from './types.js';
+/** Public Jetstream instances operated by Bluesky */
+export declare const JETSTREAM_INSTANCES: {
+    readonly 'us-east-1': "wss://jetstream1.us-east.bsky.network";
+    readonly 'us-east-2': "wss://jetstream2.us-east.bsky.network";
+    readonly 'us-west-1': "wss://jetstream1.us-west.bsky.network";
+    readonly 'us-west-2': "wss://jetstream2.us-west.bsky.network";
+};
+export type JetstreamInstance = keyof typeof JETSTREAM_INSTANCES;
+/**
+ * Client for connecting to AT Protocol Jetstream real-time event stream.
+ *
+ * @example
+ * ```typescript
+ * const client = new JetstreamClient({
+ *   wantedCollections: ['app.bsky.feed.post'],
+ *   wantedDids: ['did:plc:...'],
+ * });
+ *
+ * client.onEvent((event) => {
+ *   console.log('Received event:', event.kind, event.commit?.collection);
+ * });
+ *
+ * client.connect();
+ * ```
+ */
+export declare class JetstreamClient {
+    private ws;
+    private url;
+    private options;
+    private eventHandlers;
+    private errorHandlers;
+    private stateHandlers;
+    private reconnectAttempts;
+    private cursor;
+    private isConnecting;
+    private shouldReconnect;
+    private reconnectTimeout;
+    private _connectionState;
+    constructor(options?: JetstreamOptions);
+    /** Current connection state */
+    get connectionState(): JetstreamConnectionState;
+    /** Get current cursor (last seen time_us) */
+    getCursor(): number | undefined;
+    /** Connect to Jetstream and start receiving events */
+    connect(): void;
+    /** Disconnect from Jetstream */
+    disconnect(): void;
+    /** Subscribe to events */
+    onEvent(handler: JetstreamEventHandler): () => void;
+    /** Subscribe to errors */
+    onError(handler: JetstreamErrorHandler): () => void;
+    /** Subscribe to connection state changes */
+    onStateChange(handler: (state: JetstreamConnectionState) => void): () => void;
+    /** Update subscription filters after connecting */
+    updateFilters(options: Partial<JetstreamOptions>): void;
+    /** Set cursor for replay */
+    setCursor(cursor: number): void;
+    private buildUrl;
+    private setState;
+    private handleError;
+    private scheduleReconnect;
+}
+/**
+ * Create a Jetstream client for a specific DID's data.
+ * Filters events to only include records from the specified DID.
+ */
+export declare function createDidJetstreamClient(did: string, options?: Omit<JetstreamOptions, 'wantedDids'>): JetstreamClient;
+/**
+ * Create a Jetstream client for specific collections.
+ * Receives events for all DIDs but only for the specified collections.
+ */
+export declare function createCollectionJetstreamClient(collections: string[], options?: Omit<JetstreamOptions, 'wantedCollections'>): JetstreamClient;
+/**
+ * Create a Jetstream client for the full firehose (all collections, all DIDs).
+ * Use with caution - this receives a high volume of events.
+ */
+export declare function createFullFirehoseClient(options?: JetstreamOptions): JetstreamClient;
+/**
+ * Get the current time as a Unix microseconds cursor.
+ * Useful for starting live-tail mode.
+ */
+export declare function getCurrentCursor(): number;
+/**
+ * Convert a Unix timestamp (ms) to Jetstream cursor (microseconds).
+ */
+export declare function timestampToCursor(timestampMs: number): number;
+/**
+ * Convert a Jetstream cursor (microseconds) to Unix timestamp (ms).
+ */
+export declare function cursorToTimestamp(cursor: number): number;
+//# sourceMappingURL=jetstream.d.ts.map

package/dist/jetstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jetstream.d.ts","sourceRoot":"","sources":["../src/jetstream.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEX,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,MAAM,YAAY,CAAC;AAEpB,qDAAqD;AACrD,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAUjE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,aAAa,CAA6D;IAClF,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,gBAAgB,CAA8C;IACtE,OAAO,CAAC,gBAAgB,CAA4C;gBAExD,OAAO,GAAE,gBAAqB;IAM1C,+BAA+B;IAC/B,IAAI,eAAe,IAAI,wBAAwB,CAE9C;IAED,6CAA6C;IAC7C,SAAS,IAAI,MAAM,GAAG,SAAS;IAI/B,sDAAsD;IACtD,OAAO,IAAI,IAAI;IA0Df,gCAAgC;IAChC,UAAU,IAAI,IAAI;IAalB,0BAA0B;IAC1B,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAKnD,0BAA0B;IAC1B,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAKnD,4CAA4C;IAC5C,aAAa,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,GAAG,MAAM,IAAI;IAK7E,mDAAmD;IACnD,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAgBvD,4BAA4B;IAC5B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B,OAAO,CAAC,QAAQ;IAqChB,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,iBAAiB;CAWzB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAM,GAChD,eAAe,CAKjB;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC9C,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,mBAAmB,CAAM,GACvD,eAAe,CAKjB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CAExF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/jetstream.js

@@ -0,0 +1,270 @@
+/**
+ * Jetstream WebSocket client for AT Protocol real-time event streaming.
+ *
+ * Jetstream is a simplified JSON event stream that converts the CBOR-encoded
+ * AT Protocol firehose into lightweight, friendly JSON objects.
+ *
+ * @see https://github.com/bluesky-social/jetstream
+ */
+/** Public Jetstream instances operated by Bluesky */
+export const JETSTREAM_INSTANCES = {
+    'us-east-1': 'wss://jetstream1.us-east.bsky.network',
+    'us-east-2': 'wss://jetstream2.us-east.bsky.network',
+    'us-west-1': 'wss://jetstream1.us-west.bsky.network',
+    'us-west-2': 'wss://jetstream2.us-west.bsky.network',
+};
+/** Default instance to use */
+const DEFAULT_INSTANCE = 'us-west-2';
+/** Reconnection settings */
+const RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_DELAY_MS = 30000;
+const CURSOR_BUFFER_US = 5_000_000; // 5 seconds in microseconds
+/**
+ * Client for connecting to AT Protocol Jetstream real-time event stream.
+ *
+ * @example
+ * ```typescript
+ * const client = new JetstreamClient({
+ *   wantedCollections: ['app.bsky.feed.post'],
+ *   wantedDids: ['did:plc:...'],
+ * });
+ *
+ * client.onEvent((event) => {
+ *   console.log('Received event:', event.kind, event.commit?.collection);
+ * });
+ *
+ * client.connect();
+ * ```
+ */
+export class JetstreamClient {
+    ws = null;
+    url;
+    options;
+    eventHandlers = new Set();
+    errorHandlers = new Set();
+    stateHandlers = new Set();
+    reconnectAttempts = 0;
+    cursor;
+    isConnecting = false;
+    shouldReconnect = true;
+    reconnectTimeout = null;
+    _connectionState = 'disconnected';
+    constructor(options = {}) {
+        this.url = options.url || JETSTREAM_INSTANCES[DEFAULT_INSTANCE];
+        this.options = options;
+        this.cursor = options.cursor;
+    }
+    /** Current connection state */
+    get connectionState() {
+        return this._connectionState;
+    }
+    /** Get current cursor (last seen time_us) */
+    getCursor() {
+        return this.cursor;
+    }
+    /** Connect to Jetstream and start receiving events */
+    connect() {
+        if (this.ws?.readyState === WebSocket.OPEN || this.isConnecting) {
+            return;
+        }
+        this.isConnecting = true;
+        this.shouldReconnect = true;
+        this.setState('connecting');
+        const wsUrl = this.buildUrl();
+        try {
+            this.ws = new WebSocket(wsUrl);
+        }
+        catch (err) {
+            this.isConnecting = false;
+            this.handleError(new Error(`Failed to create WebSocket: ${err}`));
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws.onopen = () => {
+            this.isConnecting = false;
+            this.reconnectAttempts = 0;
+            this.setState('connected');
+        };
+        this.ws.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data.toString());
+                this.cursor = data.time_us;
+                this.eventHandlers.forEach((handler) => {
+                    try {
+                        handler(data);
+                    }
+                    catch (err) {
+                        console.error('[Jetstream] Handler error:', err);
+                    }
+                });
+            }
+            catch (err) {
+                console.error('[Jetstream] Failed to parse message:', err);
+            }
+        };
+        this.ws.onerror = () => {
+            this.isConnecting = false;
+            this.handleError(new Error('WebSocket error'));
+        };
+        this.ws.onclose = (event) => {
+            this.isConnecting = false;
+            if (this.shouldReconnect) {
+                this.setState('reconnecting');
+                this.scheduleReconnect();
+            }
+            else {
+                this.setState('disconnected');
+            }
+        };
+    }
+    /** Disconnect from Jetstream */
+    disconnect() {
+        this.shouldReconnect = false;
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this.setState('disconnected');
+    }
+    /** Subscribe to events */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    /** Subscribe to errors */
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    /** Subscribe to connection state changes */
+    onStateChange(handler) {
+        this.stateHandlers.add(handler);
+        return () => this.stateHandlers.delete(handler);
+    }
+    /** Update subscription filters after connecting */
+    updateFilters(options) {
+        this.options = { ...this.options, ...options };
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            const message = {
+                type: 'options_update',
+                payload: {
+                    wantedCollections: this.options.wantedCollections ?? [],
+                    wantedDids: this.options.wantedDids ?? [],
+                    maxMessageSizeBytes: this.options.maxMessageSizeBytes ?? 0,
+                },
+            };
+            this.ws.send(JSON.stringify(message));
+        }
+    }
+    /** Set cursor for replay */
+    setCursor(cursor) {
+        this.cursor = cursor;
+    }
+    buildUrl() {
+        const params = new URLSearchParams();
+        if (this.options.wantedCollections?.length) {
+            for (const collection of this.options.wantedCollections) {
+                params.append('wantedCollections', collection);
+            }
+        }
+        if (this.options.wantedDids?.length) {
+            for (const did of this.options.wantedDids) {
+                params.append('wantedDids', did);
+            }
+        }
+        if (this.options.maxMessageSizeBytes) {
+            params.set('maxMessageSizeBytes', String(this.options.maxMessageSizeBytes));
+        }
+        if (this.options.compress) {
+            params.set('compress', 'true');
+        }
+        if (this.options.requireHello) {
+            params.set('requireHello', 'true');
+        }
+        // Use cursor with buffer for gapless replay
+        if (this.cursor) {
+            const bufferedCursor = Math.max(0, this.cursor - CURSOR_BUFFER_US);
+            params.set('cursor', String(bufferedCursor));
+        }
+        const queryString = params.toString();
+        return queryString ? `${this.url}/subscribe?${queryString}` : `${this.url}/subscribe`;
+    }
+    setState(state) {
+        this._connectionState = state;
+        this.stateHandlers.forEach((handler) => {
+            try {
+                handler(state);
+            }
+            catch (err) {
+                console.error('[Jetstream] State handler error:', err);
+            }
+        });
+    }
+    handleError(error) {
+        this.errorHandlers.forEach((handler) => {
+            try {
+                handler(error);
+            }
+            catch (err) {
+                console.error('[Jetstream] Error handler error:', err);
+            }
+        });
+    }
+    scheduleReconnect() {
+        const delay = Math.min(RECONNECT_DELAY_MS * Math.pow(2, this.reconnectAttempts), MAX_RECONNECT_DELAY_MS);
+        this.reconnectAttempts++;
+        this.reconnectTimeout = setTimeout(() => {
+            this.connect();
+        }, delay);
+    }
+}
+/**
+ * Create a Jetstream client for a specific DID's data.
+ * Filters events to only include records from the specified DID.
+ */
+export function createDidJetstreamClient(did, options = {}) {
+    return new JetstreamClient({
+        ...options,
+        wantedDids: [did],
+    });
+}
+/**
+ * Create a Jetstream client for specific collections.
+ * Receives events for all DIDs but only for the specified collections.
+ */
+export function createCollectionJetstreamClient(collections, options = {}) {
+    return new JetstreamClient({
+        ...options,
+        wantedCollections: collections,
+    });
+}
+/**
+ * Create a Jetstream client for the full firehose (all collections, all DIDs).
+ * Use with caution - this receives a high volume of events.
+ */
+export function createFullFirehoseClient(options = {}) {
+    return new JetstreamClient(options);
+}
+/**
+ * Get the current time as a Unix microseconds cursor.
+ * Useful for starting live-tail mode.
+ */
+export function getCurrentCursor() {
+    return Date.now() * 1000;
+}
+/**
+ * Convert a Unix timestamp (ms) to Jetstream cursor (microseconds).
+ */
+export function timestampToCursor(timestampMs) {
+    return timestampMs * 1000;
+}
+/**
+ * Convert a Jetstream cursor (microseconds) to Unix timestamp (ms).
+ */
+export function cursorToTimestamp(cursor) {
+    return Math.floor(cursor / 1000);
+}

package/dist/musicbrainz.d.ts

@@ -5,6 +5,7 @@ export declare function searchDeezerArtwork(trackName: string, artistName: strin
 export declare function searchLastFmArtwork(trackName: string, artistName: string, releaseName?: string): Promise<string | null>;
 /**
  * Cascading artwork search: Cover Art Archive → MusicBrainz+CAA → iTunes → Last.fm
+ * Each step is bounded by ARTWORK_TIMEOUT to prevent serverless function timeouts.
  */
 export declare function findArtwork(trackName: string, artistName: string, releaseName?: string, releaseMbId?: string, fetchFn?: typeof fetch): Promise<string | null>;
 //# sourceMappingURL=musicbrainz.d.ts.map

package/dist/musicbrainz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"musicbrainz.d.ts","sourceRoot":"","sources":["../src/musicbrainz.ts"],"names":[],"mappings":"AAiBA,wBAAsB,wBAAwB,CAC7C,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB;AAkCD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,GAAG,GAAG,GAAG,GAAG,IAAU,GAAG,MAAM,CAE1F;AAED,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuBxB;AAED,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA2BxB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAChC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,KAAK,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BxB"}
+{"version":3,"file":"musicbrainz.d.ts","sourceRoot":"","sources":["../src/musicbrainz.ts"],"names":[],"mappings":"AAkCA,wBAAsB,wBAAwB,CAC7C,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB;AAkCD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,GAAG,GAAG,GAAG,GAAG,IAAU,GAAG,MAAM,CAE1F;AAED,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuBxB;AAED,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA2BxB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAChC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,KAAK,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BxB"}

package/dist/musicbrainz.js

@@ -1,4 +1,16 @@
 import { cache } from './cache.js';
+/** Timeout for individual artwork API calls (ms). */
+const ARTWORK_TIMEOUT = 5_000;
+/**
+ * Wraps a promise with a timeout. Rejects with a TimeoutError if the promise
+ * doesn't settle within `ms` milliseconds.
+ */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
 export async function searchMusicBrainzRelease(trackName, artistName, releaseName) {
     const cacheKey = `mb:release:${trackName}:${artistName}:${releaseName || 'none'}`;
     const cached = cache.get(cacheKey);
@@ -140,6 +152,7 @@ export async function searchLastFmArtwork(trackName, artistName, releaseName) {
 }
 /**
  * Cascading artwork search: Cover Art Archive → MusicBrainz+CAA → iTunes → Last.fm
+ * Each step is bounded by ARTWORK_TIMEOUT to prevent serverless function timeouts.
  */
 export async function findArtwork(trackName, artistName, releaseName, releaseMbId, fetchFn) {
     const _fetch = fetchFn || globalThis.fetch;
@@ -147,7 +160,7 @@ export async function findArtwork(trackName, artistName, releaseName, releaseMbI
     if (releaseMbId) {
         const caaUrl = buildCoverArtUrl(releaseMbId, 500);
         try {
-            const res = await _fetch(caaUrl, { method: 'HEAD' });
+            const res = await withTimeout(_fetch(caaUrl, { method: 'HEAD' }), ARTWORK_TIMEOUT);
             if (res.ok)
                 return caaUrl;
         }
@@ -158,7 +171,7 @@ export async function findArtwork(trackName, artistName, releaseName, releaseMbI
     if (mbId) {
         const caaUrl = buildCoverArtUrl(mbId, 500);
         try {
-            const res = await _fetch(caaUrl, { method: 'HEAD' });
+            const res = await withTimeout(_fetch(caaUrl, { method: 'HEAD' }), ARTWORK_TIMEOUT);
             if (res.ok)
                 return caaUrl;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ewanc26/atproto",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "AT Protocol service layer extracted from ewancroft.uk",
   "author": "Ewan Croft",
   "license": "AGPL-3.0-only",

package/src/agents.ts

@@ -2,6 +2,26 @@ import { AtpAgent } from '@atproto/api';
 import type { ResolvedIdentity } from './types.js';
 import { cache } from './cache.js';
 
+/** Default timeout for individual AT Protocol XRPC calls (ms). */
+const XRPC_TIMEOUT = 8_000;
+
+/** Default timeout for identity resolution (ms). */
+const IDENTITY_TIMEOUT = 5_000;
+
+/**
+ * Wraps a promise with a timeout. Rejects with a TimeoutError if the promise
+ * doesn't settle within `ms` milliseconds.
+ */
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms);
+		promise.then(
+			(value) => { clearTimeout(timer); resolve(value); },
+			(err) => { clearTimeout(timer); reject(err); }
+		);
+	});
+}
+
 export function createAgent(service: string, fetchFn?: typeof fetch): AtpAgent {
 	const wrappedFetch = fetchFn
 		? async (url: URL | RequestInfo, init?: RequestInit) => {
@@ -40,8 +60,11 @@ export async function resolveIdentity(
 	if (cached) return cached;
 
 	const _fetch = fetchFn ?? globalThis.fetch;
-	const response = await _fetch(
-		`https://slingshot.microcosm.blue/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${encodeURIComponent(did)}`
+	const response = await withTimeout(
+		_fetch(
+			`https://slingshot.microcosm.blue/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${encodeURIComponent(did)}`
+		),
+		IDENTITY_TIMEOUT
 	);
 
 	if (!response.ok) {
@@ -71,7 +94,10 @@ export async function getPublicAgent(did: string, fetchFn?: typeof fetch): Promi
 
 	try {
 		try {
-			const response = await constellationAgent.getProfile({ actor: did });
+			const response = await withTimeout(
+				constellationAgent.getProfile({ actor: did }),
+				XRPC_TIMEOUT
+			);
 			if (response.success) {
 				resolvedAgent = constellationAgent;
 				return resolvedAgent;
@@ -113,7 +139,7 @@ export async function withFallback<T>(
 	for (const getAgent of agents) {
 		try {
 			const agent = await getAgent();
-			return await operation(agent);
+			return await withTimeout(operation(agent), XRPC_TIMEOUT);
 		} catch (error) {
 			lastError = error;
 		}

package/src/musicbrainz.ts

@@ -1,5 +1,22 @@
 import { cache } from './cache.js';
 
+/** Timeout for individual artwork API calls (ms). */
+const ARTWORK_TIMEOUT = 5_000;
+
+/**
+ * Wraps a promise with a timeout. Rejects with a TimeoutError if the promise
+ * doesn't settle within `ms` milliseconds.
+ */
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms);
+		promise.then(
+			(value) => { clearTimeout(timer); resolve(value); },
+			(err) => { clearTimeout(timer); reject(err); }
+		);
+	});
+}
+
 interface MusicBrainzRelease {
 	id: string;
 	score: number;
@@ -147,6 +164,7 @@ export async function searchLastFmArtwork(
 
 /**
  * Cascading artwork search: Cover Art Archive → MusicBrainz+CAA → iTunes → Last.fm
+ * Each step is bounded by ARTWORK_TIMEOUT to prevent serverless function timeouts.
  */
 export async function findArtwork(
 	trackName: string,
@@ -161,7 +179,7 @@ export async function findArtwork(
 	if (releaseMbId) {
 		const caaUrl = buildCoverArtUrl(releaseMbId, 500);
 		try {
-			const res = await _fetch(caaUrl, { method: 'HEAD' });
+			const res = await withTimeout(_fetch(caaUrl, { method: 'HEAD' }), ARTWORK_TIMEOUT);
 			if (res.ok) return caaUrl;
 		} catch { /* continue */ }
 	}
@@ -171,7 +189,7 @@ export async function findArtwork(
 	if (mbId) {
 		const caaUrl = buildCoverArtUrl(mbId, 500);
 		try {
-			const res = await _fetch(caaUrl, { method: 'HEAD' });
+			const res = await withTimeout(_fetch(caaUrl, { method: 'HEAD' }), ARTWORK_TIMEOUT);
 			if (res.ok) return caaUrl;
 		} catch { /* continue */ }
 	}