scrapely 1.2.3 → 1.2.5

package/dist/storage/log-manager.d.ts

@@ -0,0 +1,114 @@
+import type { DragonflyClient } from './dragonfly-client.js';
+import type { UserPlan } from './ttl-manager.js';
+/**
+ * Log configuration
+ */
+export interface LogConfig {
+    /** Maximum log size in bytes before truncation (default: 5MB) */
+    maxLogSize: number;
+    /** S3 bucket for long-term log storage */
+    s3Bucket?: string;
+    /** S3 region */
+    s3Region?: string;
+    /** S3 endpoint (for non-AWS S3-compatible storage) */
+    s3Endpoint?: string;
+}
+/**
+ * Manages log storage in Dragonfly with optional S3 archival.
+ *
+ * Log lifecycle:
+ * 1. Logs are written to Dragonfly during execution (fast, real-time tailing)
+ * 2. Log size is capped at maxLogSize (trailing portion kept, truncated flag set)
+ * 3. After run completes, logs are uploaded to S3 for long-term storage
+ * 4. TTL in Redis is short (12h free, 7d paid) since S3 is the source of truth
+ */
+export declare class LogManager {
+    private client;
+    private config;
+    constructor(client: DragonflyClient, config?: Partial<LogConfig>);
+    /**
+     * Get the Redis key for a run's logs
+     */
+    private getLogKey;
+    /**
+     * Get the Redis key for the truncation flag on a run's logs.
+     * Set to '1' the first time the log buffer overflows maxLogSize.
+     */
+    private getTruncatedKey;
+    /**
+     * Advance a byte offset forward until it points to the start of a valid
+     * UTF-8 code-point boundary in `buf`.  Continuation bytes (10xxxxxx) are
+     * skipped so we never cut a multibyte sequence in half.
+     *
+     * Returns the adjusted offset (always ≤ buf.length).
+     */
+    private static alignUtf8Boundary;
+    /**
+     * Append log data to a run's log buffer.
+     *
+     * Implements trailing-only storage — if max size is exceeded, older data is
+     * truncated from the front.  The cut point is aligned to a UTF-8 code-point
+     * boundary so the stored string is always valid UTF-8.
+     *
+     * A separate 'truncated' flag key is set the first time an overflow happens
+     * so callers can surface a "log was truncated" notice to the user.
+     *
+     * Fix (race condition): APPEND + STRLEN are batched in a single pipeline to
+     * reduce round-trips.  The subsequent GETRANGE/SET truncation is unavoidably
+     * a second step, but at MVP scale log writes per run are effectively serial.
+     */
+    appendLog(runId: string, data: string): Promise<void>;
+    /**
+     * Get logs for a run
+     */
+    getLogs(runId: string): Promise<string | null>;
+    /**
+     * Get log size in bytes
+     */
+    getLogSize(runId: string): Promise<number>;
+    /**
+     * Set TTL on logs based on user plan.
+     * Should be called when run starts.
+     * Uses NX so a retry never resets an already-running countdown.
+     */
+    setLogTtl(runId: string, plan: UserPlan): Promise<void>;
+    /**
+     * Upload logs to S3 for long-term storage.
+     * Called after run completes.
+     */
+    uploadToS3(runId: string, userId: string): Promise<string | null>;
+    /**
+     * Delete logs from Redis (after S3 upload or when no longer needed)
+     */
+    deleteLogs(runId: string): Promise<void>;
+    /**
+     * Stream logs for real-time tailing.
+     * Returns an async generator that yields log chunks as they're written.
+     * Automatically stops when the run finishes (success, failed, timed_out, killed).
+     *
+     * Fix (offset invalidation): if a truncation has occurred since the last
+     * poll (i.e. currentLength < lastOffset), the offset is reset to 0 so we
+     * re-stream from the start of the new (shorter) buffer instead of silently
+     * dropping bytes.
+     */
+    streamLogs(runId: string, options?: {
+        pollInterval?: number;
+    }): AsyncGenerator<string, void, unknown>;
+    /**
+     * Get log metadata (for API responses).
+     *
+     * `wasTruncated` replaces the previous `hasMore: false` which was always
+     * false and conveyed no useful information.  When `wasTruncated` is true
+     * the caller should surface a notice like "Log was truncated — only the
+     * trailing portion is shown."
+     */
+    getLogMetadata(runId: string): Promise<{
+        size: number;
+        maxSize: number;
+        wasTruncated: boolean;
+    }>;
+    /**
+     * Create LogConfig from environment variables
+     */
+    static fromEnv(): LogConfig;
+}

package/dist/storage/log-manager.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogManager = void 0;
+const run_metadata_js_1 = require("./run-metadata.js");
+const DEFAULT_LOG_CONFIG = {
+    maxLogSize: 5 * 1024 * 1024, // 5MB
+};
+/**
+ * Manages log storage in Dragonfly with optional S3 archival.
+ *
+ * Log lifecycle:
+ * 1. Logs are written to Dragonfly during execution (fast, real-time tailing)
+ * 2. Log size is capped at maxLogSize (trailing portion kept, truncated flag set)
+ * 3. After run completes, logs are uploaded to S3 for long-term storage
+ * 4. TTL in Redis is short (12h free, 7d paid) since S3 is the source of truth
+ */
+class LogManager {
+    client;
+    config;
+    constructor(client, config) {
+        this.client = client;
+        this.config = { ...DEFAULT_LOG_CONFIG, ...config };
+    }
+    /**
+     * Get the Redis key for a run's logs
+     */
+    getLogKey(runId) {
+        return this.client.key('logs', runId);
+    }
+    /**
+     * Get the Redis key for the truncation flag on a run's logs.
+     * Set to '1' the first time the log buffer overflows maxLogSize.
+     */
+    getTruncatedKey(runId) {
+        return this.client.key('logs', runId, 'truncated');
+    }
+    /**
+     * Advance a byte offset forward until it points to the start of a valid
+     * UTF-8 code-point boundary in `buf`.  Continuation bytes (10xxxxxx) are
+     * skipped so we never cut a multibyte sequence in half.
+     *
+     * Returns the adjusted offset (always ≤ buf.length).
+     */
+    static alignUtf8Boundary(buf, offset) {
+        while (offset < buf.length && (buf[offset] & 0xc0) === 0x80) {
+            offset++;
+        }
+        return offset;
+    }
+    /**
+     * Append log data to a run's log buffer.
+     *
+     * Implements trailing-only storage — if max size is exceeded, older data is
+     * truncated from the front.  The cut point is aligned to a UTF-8 code-point
+     * boundary so the stored string is always valid UTF-8.
+     *
+     * A separate 'truncated' flag key is set the first time an overflow happens
+     * so callers can surface a "log was truncated" notice to the user.
+     *
+     * Fix (race condition): APPEND + STRLEN are batched in a single pipeline to
+     * reduce round-trips.  The subsequent GETRANGE/SET truncation is unavoidably
+     * a second step, but at MVP scale log writes per run are effectively serial.
+     */
+    async appendLog(runId, data) {
+        if (data === '') {
+            // Redis APPEND of an empty string still creates the key — preserve
+            // that behaviour but skip the unnecessary pipeline call.
+            const key = this.getLogKey(runId);
+            await this.client.redis.append(key, '');
+            return;
+        }
+        const key = this.getLogKey(runId);
+        const buffer = Buffer.from(data, 'utf-8');
+        // Batch APPEND + STRLEN into one pipeline to reduce round-trips
+        const pipeline = this.client.redis.pipeline();
+        pipeline.append(key, buffer);
+        pipeline.strlen(key);
+        const results = await pipeline.exec();
+        // results[1][1] is the STRLEN response
+        const currentLength = results?.[1]?.[1] ?? 0;
+        if (currentLength > this.config.maxLogSize) {
+            const rawExcess = currentLength - this.config.maxLogSize;
+            // Use getrangeBuffer to get the raw UTF-8 bytes without any ioredis
+            // string decoding.  If we used getrange(), ioredis would UTF-8-decode
+            // the bytes into a JS string, and re-encoding with Buffer.from(s,'binary')
+            // would corrupt multi-byte sequences (latin-1 ≠ utf-8 for high bytes).
+            const trailingBuf = await this.client.redis.getrangeBuffer(key, rawExcess, -1);
+            // Advance past any UTF-8 continuation bytes (10xxxxxx) so we start at
+            // a valid code-point boundary and never store a broken sequence.
+            const alignedOffset = LogManager.alignUtf8Boundary(trailingBuf, 0);
+            const safeTrailing = trailingBuf.subarray(alignedOffset);
+            // Overwrite the key with only the safe trailing portion
+            await this.client.redis.set(key, safeTrailing);
+            // Mark log as truncated (NX — only set once; ignore if already set)
+            await this.client.redis.set(this.getTruncatedKey(runId), '1', 'NX');
+        }
+    }
+    /**
+     * Get logs for a run
+     */
+    async getLogs(runId) {
+        const key = this.getLogKey(runId);
+        return await this.client.redis.get(key);
+    }
+    /**
+     * Get log size in bytes
+     */
+    async getLogSize(runId) {
+        const key = this.getLogKey(runId);
+        return await this.client.redis.strlen(key);
+    }
+    /**
+     * Set TTL on logs based on user plan.
+     * Should be called when run starts.
+     * Uses NX so a retry never resets an already-running countdown.
+     */
+    async setLogTtl(runId, plan) {
+        const key = this.getLogKey(runId);
+        const ttl = this.client.ttlManager.getTtl('logs', plan);
+        if (ttl !== null && ttl > 0) {
+            await this.client.ttlManager.setExpiry(this.client.redis, [key], ttl);
+        }
+    }
+    /**
+     * Upload logs to S3 for long-term storage.
+     * Called after run completes.
+     */
+    async uploadToS3(runId, userId) {
+        if (!this.config.s3Bucket) {
+            console.log(`[LogManager] S3 not configured, skipping upload for run ${runId}`);
+            return null;
+        }
+        const logs = await this.getLogs(runId);
+        if (!logs) {
+            console.log(`[LogManager] No logs to upload for run ${runId}`);
+            return null;
+        }
+        const s3Key = `logs/${userId}/${runId}.log`;
+        // Note: NOT DONE — wire up AWS SDK upload here
+        return s3Key;
+    }
+    /**
+     * Delete logs from Redis (after S3 upload or when no longer needed)
+     */
+    async deleteLogs(runId) {
+        const pipeline = this.client.redis.pipeline();
+        pipeline.del(this.getLogKey(runId));
+        pipeline.del(this.getTruncatedKey(runId));
+        await pipeline.exec();
+    }
+    /**
+     * Stream logs for real-time tailing.
+     * Returns an async generator that yields log chunks as they're written.
+     * Automatically stops when the run finishes (success, failed, timed_out, killed).
+     *
+     * Fix (offset invalidation): if a truncation has occurred since the last
+     * poll (i.e. currentLength < lastOffset), the offset is reset to 0 so we
+     * re-stream from the start of the new (shorter) buffer instead of silently
+     * dropping bytes.
+     */
+    async *streamLogs(runId, options) {
+        const pollInterval = options?.pollInterval ?? 100;
+        const key = this.getLogKey(runId);
+        const metadataManager = new run_metadata_js_1.RunMetadataManager(this.client);
+        let lastOffset = 0;
+        const finishedStatuses = ['success', 'failed', 'timed_out', 'killed'];
+        while (true) {
+            // Check if run is still active
+            const metadata = await metadataManager.get(runId);
+            // If metadata is null the run doesn't exist (never created or already deleted).
+            // Treat this as a terminal condition — yield any buffered bytes and stop.
+            if (!metadata) {
+                const currentLength = await this.client.redis.strlen(key);
+                // Reset offset if the buffer was truncated underneath us
+                if (currentLength < lastOffset)
+                    lastOffset = 0;
+                if (currentLength > lastOffset) {
+                    const remaining = await this.client.redis.getrange(key, lastOffset, -1);
+                    if (remaining)
+                        yield remaining;
+                }
+                return;
+            }
+            if (finishedStatuses.includes(metadata.status)) {
+                // Run finished — yield any remaining logs and stop
+                const currentLength = await this.client.redis.strlen(key);
+                // Reset offset if the buffer was truncated underneath us
+                if (currentLength < lastOffset)
+                    lastOffset = 0;
+                if (currentLength > lastOffset) {
+                    const remaining = await this.client.redis.getrange(key, lastOffset, -1);
+                    if (remaining)
+                        yield remaining;
+                }
+                return;
+            }
+            // Yield any new logs
+            const currentLength = await this.client.redis.strlen(key);
+            if (currentLength < lastOffset) {
+                // Buffer was truncated while we were streaming — reset and re-read
+                lastOffset = 0;
+            }
+            if (currentLength > lastOffset) {
+                const newData = await this.client.redis.getrange(key, lastOffset, -1);
+                if (newData) {
+                    yield newData;
+                }
+                lastOffset = currentLength;
+            }
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+        }
+    }
+    /**
+     * Get log metadata (for API responses).
+     *
+     * `wasTruncated` replaces the previous `hasMore: false` which was always
+     * false and conveyed no useful information.  When `wasTruncated` is true
+     * the caller should surface a notice like "Log was truncated — only the
+     * trailing portion is shown."
+     */
+    async getLogMetadata(runId) {
+        const [size, truncatedFlag] = await Promise.all([
+            this.getLogSize(runId),
+            this.client.redis.get(this.getTruncatedKey(runId)),
+        ]);
+        return {
+            size,
+            maxSize: this.config.maxLogSize,
+            wasTruncated: truncatedFlag === '1',
+        };
+    }
+    /**
+     * Create LogConfig from environment variables
+     */
+    static fromEnv() {
+        return {
+            maxLogSize: parseInt(process.env.SCRAPELY_LOG_MAX_SIZE ?? '', 10) || DEFAULT_LOG_CONFIG.maxLogSize,
+            s3Bucket: process.env.SCRAPELY_S3_LOG_BUCKET,
+            s3Region: process.env.SCRAPELY_S3_REGION || 'us-east-1',
+            s3Endpoint: process.env.SCRAPELY_S3_ENDPOINT,
+        };
+    }
+}
+exports.LogManager = LogManager;

package/dist/storage/patch-storage.d.ts

@@ -0,0 +1,11 @@
+import type { Configuration } from '../configuration.js';
+import { ApiStorageClientFactory, type ApiStorageConfig } from './api-storage-client.js';
+/**
+ * Configure API-based storage (for secure container execution).
+ * No DB credentials are exposed - only the user's API key.
+ * This is the ONLY way containers should access storage.
+ */
+export declare function setApiStorage(apiConfig: ApiStorageConfig, configuration?: Configuration): ApiStorageClientFactory;
+export declare function getApiStorageFactory(): ApiStorageClientFactory | null;
+export declare function isApiStorageConfigured(): boolean;
+export declare function disconnectStorage(): void;

package/dist/storage/patch-storage.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setApiStorage = setApiStorage;
+exports.getApiStorageFactory = getApiStorageFactory;
+exports.isApiStorageConfigured = isApiStorageConfigured;
+exports.disconnectStorage = disconnectStorage;
+const core_1 = require("@crawlee/core");
+const configuration_js_1 = require("../configuration.js");
+const api_storage_client_js_1 = require("./api-storage-client.js");
+let _apiFactory = null;
+/**
+ * Cache for auto-saved values. Map structure: storeId -> key -> value
+ * This allows getAutoSavedValue to return the same object reference,
+ * and persistState listeners can iterate and save all cached values.
+ */
+const autoSaveCache = new Map();
+/**
+ * Track which stores have registered persistState listeners
+ */
+const persistStateRegistered = new Set();
+/**
+ * Register a persistState listener for a store if not already registered.
+ * This listener saves all cached values for that store when persistState is emitted.
+ */
+function ensurePersistStateListener(storeId, config) {
+    if (persistStateRegistered.has(storeId)) {
+        return;
+    }
+    const eventManager = config.getEventManager();
+    const persistStateIntervalMillis = config.get('persistStateIntervalMillis') ?? 60000;
+    // Use half the interval for timeout (matching Crawlee's approach)
+    const timeoutSecs = persistStateIntervalMillis / 2000;
+    eventManager.on('persistState', async () => {
+        const storeCache = autoSaveCache.get(storeId);
+        if (!storeCache)
+            return;
+        const factory = _apiFactory;
+        if (!factory)
+            return;
+        const kvClient = factory.keyValueStore(storeId);
+        const promises = [];
+        for (const [key, value] of storeCache) {
+            promises.push(kvClient.setRecord({ key, value }, { timeoutSecs, doNotRetryTimeouts: true }).catch((error) => {
+                console.warn(`[Scrapely] Failed to persist state value to ${key}:`, error.message);
+            }));
+        }
+        await Promise.all(promises);
+    });
+    persistStateRegistered.add(storeId);
+}
+/**
+ * Configure API-based storage (for secure container execution).
+ * No DB credentials are exposed - only the user's API key.
+ * This is the ONLY way containers should access storage.
+ */
+function setApiStorage(apiConfig, configuration) {
+    _apiFactory = new api_storage_client_js_1.ApiStorageClientFactory(apiConfig);
+    const cfg = configuration ?? configuration_js_1.Configuration.getGlobalConfig();
+    cfg.useStorageClient(_apiFactory);
+    // Patch KeyValueStore to expose listKeys method
+    patchKeyValueStore();
+    return _apiFactory;
+}
+/**
+ * Patch KeyValueStore to expose listKeys, getAutoSavedValue, and getPublicUrl methods
+ * that delegate to the underlying client. forEachKey is left to Crawlee's native
+ * paginating implementation (via client.listKeys).
+ */
+function patchKeyValueStore() {
+    const origOpen = core_1.KeyValueStore.open.bind(core_1.KeyValueStore);
+    // Override the open method to return a patched store
+    core_1.KeyValueStore.open = async function (id) {
+        const store = await origOpen(id);
+        // Add listKeys if not already present
+        if (!store.listKeys) {
+            const storeId = store.id || store.name || 'default';
+            store.listKeys = async function (options) {
+                const factory = _apiFactory;
+                if (!factory) {
+                    throw new Error('API storage client not initialized');
+                }
+                const kvClient = factory.keyValueStore(storeId);
+                return kvClient.listKeys(options);
+            };
+        }
+        // Always override keys() — Crawlee's built-in keys() is an async generator
+        // that only runs when iterated with `for await`. Actors that call `await kvs.keys()`
+        // without iterating never trigger billing. Replace it with a Promise-based version
+        // that calls _listKeys() immediately (and thus increments listCount for billing).
+        {
+            const storeId = store.id || store.name || 'default';
+            store.keys = async function (options) {
+                const factory = _apiFactory;
+                if (!factory) {
+                    throw new Error('API storage client not initialized');
+                }
+                const kvClient = factory.keyValueStore(storeId);
+                return kvClient.keys(options);
+            };
+        }
+        // Add getAutoSavedValue method - returns value with auto-save behavior
+        // This implementation matches Crawlee's approach:
+        // 1. Check cache first (return same object reference for subsequent calls)
+        // 2. Fetch value from storage if not cached
+        // 3. Cache the value (so mutations are tracked)
+        // 4. Register persistState listener to save cached values
+        {
+            const storeId = store.id || store.name || 'default';
+            const config = configuration_js_1.Configuration.getGlobalConfig();
+            store.getAutoSavedValue = async function (key, defaultValue) {
+                // Check if we have a cached value for this store/key
+                let storeCache = autoSaveCache.get(storeId);
+                if (storeCache?.has(key)) {
+                    return storeCache.get(key);
+                }
+                // Fetch value from storage
+                const factory = _apiFactory;
+                if (!factory) {
+                    throw new Error('API storage client not initialized');
+                }
+                const kvClient = factory.keyValueStore(storeId);
+                // Get the value (this stores defaultValue if key doesn't exist)
+                const value = await kvClient.getAutoSavedValue(key, defaultValue);
+                // Initialize store cache if needed
+                if (!storeCache) {
+                    storeCache = new Map();
+                    autoSaveCache.set(storeId, storeCache);
+                }
+                // Check cache again (race condition: another call might have cached it)
+                if (storeCache.has(key)) {
+                    return storeCache.get(key);
+                }
+                // Cache the value - mutations to this object will be persisted
+                storeCache.set(key, value);
+                // Register persistState listener for this store
+                ensurePersistStateListener(storeId, config);
+                return value;
+            };
+        }
+        // Add getPublicUrl method - returns public URL for a record
+        {
+            const storeId = store.id || store.name || 'default';
+            store.getPublicUrl = function (key) {
+                const factory = _apiFactory;
+                if (!factory) {
+                    throw new Error('API storage client not initialized');
+                }
+                const kvClient = factory.keyValueStore(storeId);
+                return kvClient.getPublicUrl(key);
+            };
+        }
+        return store;
+    };
+    // Add static getAutoSavedValue method - operates on default store
+    core_1.KeyValueStore.getAutoSavedValue = async function (key, defaultValue) {
+        const store = await core_1.KeyValueStore.open();
+        return store.getAutoSavedValue(key, defaultValue);
+    };
+    // Add static recordExists method - operates on default store
+    core_1.KeyValueStore.recordExists = async function (key) {
+        const store = await core_1.KeyValueStore.open();
+        return store.recordExists(key);
+    };
+}
+function getApiStorageFactory() {
+    return _apiFactory;
+}
+function isApiStorageConfigured() {
+    return _apiFactory !== null;
+}
+function disconnectStorage() {
+    // API storage doesn't need explicit disconnect
+    _apiFactory = null;
+    // Clear caches and listener registrations
+    autoSaveCache.clear();
+    persistStateRegistered.clear();
+}

package/dist/storage/request-queue-client.d.ts

@@ -0,0 +1,93 @@
+import type { RequestQueueClient, RequestQueueInfo, QueueHead, QueueOperationInfo, RequestSchema, UpdateRequestSchema, RequestOptions, BatchAddRequestsResult, ListOptions, ListAndLockOptions, ListAndLockHeadResult, ProlongRequestLockOptions, ProlongRequestLockResult, DeleteRequestLockOptions } from '@crawlee/types';
+export type { RequestQueueRequest } from './rq-list-requests.js';
+/** Options for listRequests endpoint */
+export interface ListRequestsOptions {
+    limit?: number;
+    cursor?: string;
+    exclusiveStartId?: string;
+    filter?: ('locked' | 'pending')[];
+    clientKey?: string;
+}
+/** Result from listRequests endpoint */
+export interface ListRequestsResult {
+    items: RequestQueueRequest[];
+    count: number;
+    limit: number;
+    exclusiveStartId?: string;
+    cursor?: string;
+    nextCursor?: string;
+}
+import type { DragonflyClient } from './dragonfly-client.js';
+import type { RequestQueueOptions } from '@crawlee/types';
+import { type RequestQueueRequest } from './rq-list-requests.js';
+export declare class DragonflyRequestQueueClient implements RequestQueueClient {
+    private client;
+    private id;
+    private infoKey;
+    private requestsKey;
+    private pendingKey;
+    private lockedKey;
+    private lockOwnersKey;
+    private readonly clientKey;
+    constructor(client: DragonflyClient, id: string, options?: RequestQueueOptions);
+    private estimateStoredRequestBytes;
+    /**
+     * Track a write operation for billing.
+     */
+    private trackWrite;
+    /**
+     * Track a read operation for billing.
+     */
+    private trackRead;
+    /**
+     * Track storage bytes for billing.
+     */
+    private trackStorageBytes;
+    /**
+     * Track clientKey access for hadMultipleClients (per Apify spec).
+     * Returns the current hadMultipleClients flag after update.
+     */
+    private trackClientKey;
+    get(): Promise<RequestQueueInfo | undefined>;
+    update(newFields: {
+        name?: string;
+    }): Promise<Partial<RequestQueueInfo> | undefined>;
+    delete(): Promise<void>;
+    addRequest(request: RequestSchema, options?: RequestOptions): Promise<QueueOperationInfo>;
+    batchAddRequests(requests: RequestSchema[], options?: RequestOptions): Promise<BatchAddRequestsResult>;
+    getRequest(id: string): Promise<RequestOptions | undefined>;
+    updateRequest(request: UpdateRequestSchema, options?: RequestOptions): Promise<QueueOperationInfo>;
+    deleteRequest(id: string): Promise<void>;
+    listHead(options?: ListOptions): Promise<QueueHead>;
+    /**
+     * List all requests in the queue with optional filtering and pagination.
+     * Supports cursor-based pagination (preferred) and deprecated exclusiveStartId.
+     * @param options.limit - Max number of requests to return (default 100, max 10000)
+     * @param options.cursor - Base64-encoded cursor from previous response.
+     *        If the cursor's request was deleted, listing resumes just past its
+     *        sorted position (it never restarts from the first page).
+     * @param options.exclusiveStartId - DEPRECATED: Skip requests up to this ID
+     * @param options.filter - Filter by state: 'locked' or 'pending'
+     * @param options.clientKey - Client identifier for hadMultipleClients tracking
+     */
+    listRequests(options?: ListRequestsOptions): Promise<ListRequestsResult>;
+    listAndLockHead(options: ListAndLockOptions & {
+        clientKey?: string;
+    }): Promise<ListAndLockHeadResult>;
+    prolongRequestLock(id: string, options: ProlongRequestLockOptions): Promise<ProlongRequestLockResult>;
+    deleteRequestLock(id: string, options?: DeleteRequestLockOptions): Promise<void>;
+    /**
+     * Unlock all requests locked by a specific clientKey.
+     * This is useful for batch unlocking when a client is done processing.
+     * @param options.clientKey - The client key to unlock requests for
+     * @param options.forefront - If true, move unlocked requests to the front of the queue
+     * @param options.runId - Optional run ID to only unlock requests for a specific run
+     */
+    unlockRequests(options: {
+        clientKey: string;
+        forefront?: boolean;
+        runId?: string;
+    }): Promise<{
+        unlockedCount: number;
+    }>;
+}