@pol-studios/powersync 1.0.6 → 1.0.10

package/dist/pol-attachment-queue-BVAIueoP.d.ts

@@ -0,0 +1,817 @@
+import { AbstractAttachmentQueue, AttachmentQueueOptions, AttachmentRecord as AttachmentRecord$1 } from '@powersync/attachments';
+import { AbstractPowerSyncDatabase } from '@powersync/common';
+import { PlatformAdapter } from './platform/index.js';
+
+/**
+ * Attachment Queue Types for @pol-studios/powersync
+ *
+ * This module re-exports types from the official @powersync/attachments package
+ * and extends them with POL-specific features like:
+ * - FAILED_PERMANENT state for permanent upload failures
+ * - Upload metadata fields for retry tracking
+ * - Source table configuration for flexible attachment watching
+ * - Image compression configuration
+ *
+ * IMPORTANT: The official AttachmentState enum has different numeric values:
+ *   Official: QUEUED_SYNC=0, QUEUED_UPLOAD=1, QUEUED_DOWNLOAD=2, SYNCED=3, ARCHIVED=4
+ *
+ * We extend this with FAILED_PERMANENT=5 for permanent upload failures.
+ */
+
+/**
+ * Extended attachment state that includes permanent failure state.
+ *
+ * Values 0-4 match the official @powersync/attachments AttachmentState.
+ * Value 5 (FAILED_PERMANENT) is our extension for uploads that have
+ * exhausted retries or encountered unrecoverable errors.
+ *
+ * @example
+ * ```typescript
+ * import { AttachmentState } from '@powersync/attachments';
+ * import { PolAttachmentState } from '@pol-studios/powersync/attachments';
+ *
+ * // Use official states
+ * const queued = AttachmentState.QUEUED_UPLOAD;
+ *
+ * // Use our extension
+ * const failed = PolAttachmentState.FAILED_PERMANENT;
+ * ```
+ */
+declare enum PolAttachmentState {
+    /** Check if the attachment needs to be uploaded or downloaded */
+    QUEUED_SYNC = 0,
+    /** Attachment to be uploaded */
+    QUEUED_UPLOAD = 1,
+    /** Attachment to be downloaded */
+    QUEUED_DOWNLOAD = 2,
+    /** Attachment has been synced */
+    SYNCED = 3,
+    /** Attachment has been orphaned, i.e. the associated record has been deleted */
+    ARCHIVED = 4,
+    /** Permanently failed (exhausted retries or unrecoverable error) - POL extension */
+    FAILED_PERMANENT = 5,
+    /** Download was skipped due to downloadFilter returning false - POL extension */
+    DOWNLOAD_SKIPPED = 6
+}
+/**
+ * Extended attachment record with POL-specific upload tracking fields.
+ *
+ * Extends the official AttachmentRecord with fields for:
+ * - Upload retry tracking
+ * - Error information
+ * - Upload metadata for onComplete callbacks
+ */
+interface PolAttachmentRecord {
+    /** Unique identifier (typically storage path) */
+    id: string;
+    /** Filename for display and type inference */
+    filename: string;
+    /** Local file URI (set after download/upload) */
+    local_uri?: string | null;
+    /** File size in bytes */
+    size?: number;
+    /** MIME type of the file */
+    media_type?: string;
+    /** Timestamp when the attachment was created/modified */
+    timestamp?: number;
+    /** Current state in the queue */
+    state: number;
+    /** Local file URI in managed cache (for uploads) */
+    upload_source_uri?: string | null;
+    /** Last upload error message */
+    upload_error?: string | null;
+    /** HTTP status or error code */
+    upload_error_code?: string | null;
+    /** Number of upload retry attempts */
+    upload_retry_count?: number;
+    /** Timestamp for next retry */
+    upload_next_retry_at?: number;
+    /** JSON-serialized entity metadata for onComplete */
+    upload_metadata?: string | null;
+    /** Target storage bucket ID */
+    upload_bucket_id?: string | null;
+}
+/**
+ * Legacy configuration for watching a source table.
+ * @deprecated Use AttachmentSourceConfig with watchIds callback instead.
+ * This interface is kept for backward compatibility with query-builder utilities.
+ */
+interface WatchConfig {
+    /** Source table name */
+    table: string;
+    /** Column containing attachment ID/path */
+    idColumn: string;
+    /** Additional columns to include in context */
+    selectColumns?: string[];
+    /** Optional WHERE clause fragment (e.g., "storagePath IS NOT NULL") */
+    where?: string;
+    /** Order by column and direction */
+    orderBy?: {
+        column: string;
+        direction: "ASC" | "DESC";
+    };
+}
+/**
+ * Legacy context for batch filtering of attachments.
+ * @deprecated Use SkipDownloadContext with skipDownload callback instead.
+ */
+interface BatchFilterContext {
+    /** All pending attachment IDs */
+    ids: string[];
+    /** Source records from watch config (ID → record) */
+    records: Map<string, Record<string, unknown>>;
+    /** Database access for batch queries */
+    db: {
+        getAll<T>(sql: string, params?: unknown[]): Promise<T[]>;
+        getOptional<T>(sql: string, params?: unknown[]): Promise<T | null>;
+    };
+}
+/**
+ * Configuration for an attachment source.
+ *
+ * This is a minimal, framework-agnostic interface for configuring attachment sync.
+ * It uses a reactive callback pattern that works with any data layer.
+ *
+ * @example
+ * ```typescript
+ * const config: AttachmentSourceConfig = {
+ *   bucket: 'project-assets',
+ *
+ *   // Reactive source of attachment IDs
+ *   watchIds: (db, onUpdate) => {
+ *     // Using PowerSync's watch API
+ *     db.watch('SELECT storagePath FROM photos WHERE storagePath IS NOT NULL', [], {
+ *       onResult: (results) => {
+ *         onUpdate(results.rows._array.map(r => r.storagePath));
+ *       }
+ *     });
+ *   },
+ *
+ *   // Optional: skip downloading videos
+ *   skipDownload: async ({ ids, db }) => {
+ *     const videos = await db.getAll<{ path: string }>(
+ *       `SELECT storagePath as path FROM photos WHERE storagePath IN (${ids.map(() => '?').join(',')}) AND mediaType LIKE 'video/%'`,
+ *       ids
+ *     );
+ *     return videos.map(v => v.path);
+ *   }
+ * };
+ * ```
+ */
+interface AttachmentSourceConfig {
+    /**
+     * Storage bucket name for this attachment source.
+     * Maps to the Supabase Storage bucket (or equivalent in other backends).
+     */
+    bucket: string;
+    /**
+     * Reactive source of attachment IDs. Called once during initialization.
+     *
+     * This callback should set up a reactive subscription that calls `onUpdate`
+     * whenever the set of attachment IDs changes. The queue will:
+     * - Queue downloads for new IDs on first emission
+     * - Queue downloads for IDs that appear in subsequent emissions
+     * - Auto-archive attachments whose IDs disappear from emissions
+     *
+     * @param db - PowerSync database instance for querying
+     * @param onUpdate - Callback to emit current set of attachment IDs
+     * @returns Optional cleanup function to dispose of the watch subscription
+     *
+     * @example
+     * ```typescript
+     * watchIds: (db, onUpdate) => {
+     *   const abort = new AbortController();
+     *   db.watch(
+     *     'SELECT storagePath FROM photos WHERE storagePath IS NOT NULL',
+     *     [],
+     *     { onResult: (r) => onUpdate(r.rows._array.map(row => row.storagePath)) },
+     *     { signal: abort.signal }
+     *   );
+     *   return () => abort.abort(); // Cleanup function
+     * }
+     * ```
+     */
+    watchIds: (db: AbstractPowerSyncDatabase, onUpdate: (ids: string[]) => void) => (() => void) | void;
+    /**
+     * Optional batch filter to skip downloading certain attachments.
+     *
+     * Called with all pending attachment IDs. Return the IDs that should
+     * be SKIPPED (not downloaded). Useful for:
+     * - Filtering out video files on mobile
+     * - Skipping large files
+     * - Conditional download based on user preferences
+     *
+     * @param context - Contains pending IDs and database access
+     * @returns Promise resolving to array of IDs to skip
+     *
+     * @example
+     * ```typescript
+     * skipDownload: async ({ ids, db }) => {
+     *   // Skip video files
+     *   const videos = await db.getAll<{ id: string }>(
+     *     `SELECT storagePath as id FROM photos
+     *      WHERE storagePath IN (${ids.map(() => '?').join(',')})
+     *      AND mediaType LIKE 'video/%'`,
+     *     ids
+     *   );
+     *   return videos.map(v => v.id);
+     * }
+     * ```
+     */
+    skipDownload?: (context: SkipDownloadContext) => Promise<string[]>;
+}
+/**
+ * Context passed to the skipDownload callback.
+ */
+interface SkipDownloadContext {
+    /** All pending attachment IDs to evaluate */
+    ids: string[];
+    /** PowerSync database instance for queries */
+    db: AbstractPowerSyncDatabase;
+}
+/**
+ * Full attachment configuration including source configs and handlers.
+ * This extends the source config with upload/download handlers and callbacks.
+ */
+interface AttachmentConfig {
+    /** Bucket name in Supabase storage */
+    bucket: string;
+    /**
+     * Reactive source of attachment IDs. Called once during initialization.
+     * May return an optional cleanup function to dispose of the watch subscription.
+     * @see AttachmentSourceConfig.watchIds
+     */
+    watchIds: AttachmentSourceConfig["watchIds"];
+    /**
+     * Optional batch filter to skip downloading certain attachments.
+     * @see AttachmentSourceConfig.skipDownload
+     */
+    skipDownload?: AttachmentSourceConfig["skipDownload"];
+    /** Optional: callback when upload completes */
+    onUploadComplete?: (attachment: AttachmentRecord) => void;
+    /** Optional: callback when upload fails */
+    onUploadFailed?: (attachment: AttachmentRecord, error: Error) => void;
+    /** Optional: max cache size in bytes */
+    maxCacheBytes?: number;
+    /** Optional: remote storage adapter for downloads */
+    remoteStorage?: AttachmentStorageAdapter;
+    /** Optional: upload handler for uploads */
+    uploadHandler?: UploadHandler;
+    /**
+     * Optional: image compression settings for downloads.
+     * Uses Supabase's transform feature to resize/compress images on download.
+     * Only applies to supported image formats (jpg, png, webp, avif, gif, heic).
+     */
+    compression?: Partial<CompressionConfig>;
+    /**
+     * Optional: download configuration for performance tuning.
+     * Adjusts concurrency and timeout for downloads.
+     * Higher concurrency = faster but more memory/network usage.
+     */
+    download?: Partial<DownloadConfig>;
+}
+/**
+ * Interface for remote attachment storage operations (e.g., Supabase Storage).
+ *
+ * This is used by PolStorageAdapter to handle remote file operations.
+ * For local file operations, we use PlatformAdapter.fileSystem.
+ */
+interface AttachmentStorageAdapter {
+    /**
+     * Download a file from remote storage.
+     *
+     * This method can return different types depending on the implementation:
+     *
+     * 1. **Blob** (legacy behavior): The file data as a Blob object.
+     *    Used by web platforms or legacy adapters. This path loads the entire
+     *    file into memory.
+     *
+     * 2. **Base64 string**: The file data encoded as a base64 string.
+     *    Will be converted to Blob by the caller.
+     *
+     * 3. **file:// URI string** (optimized path): A `file://` URI pointing to a
+     *    temp file on the local filesystem. This is the **preferred return type**
+     *    for native platforms as it enables zero-memory-overhead downloads.
+     *    When this is returned, PolAttachmentQueue.downloadRecord() uses direct
+     *    file copy instead of loading the file into JS memory, avoiding ~4x
+     *    memory overhead and OOM crashes on large files.
+     *
+     * @param filePath - The storage path of the file
+     * @returns The file data as a Blob, base64 string, or file:// URI to a temp file
+     */
+    downloadFile(filePath: string): Promise<Blob | string>;
+    /**
+     * Upload a file to remote storage (optional - not all queues need upload).
+     * @param filePath - The storage path to upload to
+     * @param data - The file data to upload (base64 string or Blob)
+     */
+    uploadFile?(filePath: string, data: Blob | string): Promise<void>;
+    /**
+     * Delete a file from remote storage (optional).
+     * @param filePath - The storage path of the file
+     */
+    deleteFile?(filePath: string): Promise<void>;
+    /**
+     * Resolve the storage bucket for a file path.
+     * Allows routing different files to different buckets.
+     * @param filePath - The file path to resolve
+     * @returns The bucket name
+     */
+    resolveBucket?(filePath: string): string;
+}
+/**
+ * Configuration for image compression.
+ */
+interface CompressionConfig {
+    /** Enable compression (default: true) */
+    enabled: boolean;
+    /** Compression quality 0.0-1.0 (default: 0.7) */
+    quality: number;
+    /** Max width before resizing (default: 2048) */
+    maxWidth: number;
+    /** Skip files under this size in bytes (default: 100KB) */
+    skipSizeBytes: number;
+    /** Skip if already under this size in bytes (default: 300KB) */
+    targetSizeBytes: number;
+}
+/**
+ * Default compression configuration.
+ */
+declare const DEFAULT_COMPRESSION_CONFIG: CompressionConfig;
+/**
+ * Configuration for the upload engine.
+ */
+interface UploadConfig {
+    /** Maximum concurrent uploads (default: 3) */
+    concurrency: number;
+    /** Upload timeout per file in ms (default: 120000) */
+    timeoutMs: number;
+    /** Base retry delay in ms (default: 5000) */
+    baseRetryDelayMs: number;
+    /** Maximum retry delay in ms (default: 3600000 = 1 hour) */
+    maxRetryDelayMs: number;
+    /** Days before marking upload as stale (default: 7) */
+    staleDaysThreshold: number;
+    /** Maximum number of retry attempts before marking as FAILED_PERMANENT (default: 100) */
+    maxRetryCount: number;
+}
+/**
+ * Default upload configuration.
+ *
+ * Note: baseRetryDelayMs is set to 30s (not 5s) to reduce battery consumption.
+ * The exponential backoff sequence will be: 30s, 60s, 2min, 4min, 8min, 16min, 32min, 1hr (capped).
+ */
+declare const DEFAULT_UPLOAD_CONFIG: UploadConfig;
+/**
+ * Interface for handling file uploads to remote storage.
+ * Separate from AttachmentStorageAdapter to allow different implementations.
+ */
+interface UploadHandler {
+    /**
+     * Upload a file to remote storage.
+     * @param storagePath - The storage path to upload to
+     * @param localFileUri - Local file URI to upload from
+     * @param mediaType - MIME type of the file
+     * @param signal - Optional AbortSignal for cancellation support
+     */
+    uploadFile(storagePath: string, localFileUri: string, mediaType: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Optional: resolve the storage bucket for a file path.
+     * @param storagePath - The file path to resolve
+     * @returns The bucket name
+     */
+    resolveBucket?(storagePath: string): string;
+}
+/**
+ * Configuration for the download engine.
+ *
+ * Note: These settings are for developers tuning performance.
+ * Higher concurrency can speed up downloads but uses more memory and network.
+ */
+interface DownloadConfig {
+    /** Maximum concurrent downloads (default: 3) */
+    concurrency: number;
+    /** Download timeout per file in ms (default: 120000 = 2 minutes) */
+    timeoutMs: number;
+}
+/**
+ * Default download configuration.
+ */
+declare const DEFAULT_DOWNLOAD_CONFIG: DownloadConfig;
+/**
+ * Configuration for cache management.
+ *
+ * By default, cache size is unlimited. Set `maxSize` to enable size-based eviction.
+ */
+interface CacheConfig {
+    /** Maximum cache size in bytes. Default: unlimited (Number.MAX_SAFE_INTEGER) */
+    maxSize: number;
+    /** Stop downloads at this percentage of max (default: 0.95 = 95%). Only applies when maxSize is set. */
+    downloadStopThreshold: number;
+    /** Trigger eviction at this percentage (default: 1.0 = 100%). Only applies when maxSize is set. */
+    evictionTriggerThreshold: number;
+}
+/**
+ * Default cache configuration.
+ *
+ * Cache size is unlimited by default. Users can set `maxSize` to enable
+ * size-based eviction when storage space is a concern.
+ */
+declare const DEFAULT_CACHE_CONFIG: CacheConfig;
+/**
+ * Predefined cache size presets in bytes.
+ * Use these constants for user-facing cache limit settings.
+ *
+ * @example
+ * ```typescript
+ * // In settings UI
+ * const options = [
+ *   { label: '250 MB', value: CACHE_SIZE_PRESETS.MB_250 },
+ *   { label: '500 MB', value: CACHE_SIZE_PRESETS.MB_500 },
+ *   { label: '1 GB', value: CACHE_SIZE_PRESETS.GB_1 },
+ *   { label: '2 GB', value: CACHE_SIZE_PRESETS.GB_2 },
+ *   { label: '5 GB', value: CACHE_SIZE_PRESETS.GB_5 },
+ *   { label: 'Unlimited', value: CACHE_SIZE_PRESETS.UNLIMITED },
+ * ];
+ *
+ * // In config
+ * cache: { maxSize: CACHE_SIZE_PRESETS.GB_1 }
+ * ```
+ */
+declare const CACHE_SIZE_PRESETS: {
+    /** 250 MB */
+    readonly MB_250: number;
+    /** 500 MB */
+    readonly MB_500: number;
+    /** 1 GB */
+    readonly GB_1: number;
+    /** 2 GB */
+    readonly GB_2: number;
+    /** 5 GB */
+    readonly GB_5: number;
+    /** Unlimited (no cache eviction) */
+    readonly UNLIMITED: number;
+};
+/**
+ * Type for cache size preset keys.
+ */
+type CacheSizePreset = keyof typeof CACHE_SIZE_PRESETS;
+/**
+ * Type for cache size preset values.
+ */
+type CacheSizeValue = (typeof CACHE_SIZE_PRESETS)[CacheSizePreset];
+/**
+ * Helper to format bytes as human-readable string.
+ *
+ * @example
+ * ```typescript
+ * formatCacheSize(CACHE_SIZE_PRESETS.GB_1) // "1 GB"
+ * formatCacheSize(CACHE_SIZE_PRESETS.MB_500) // "500 MB"
+ * formatCacheSize(CACHE_SIZE_PRESETS.UNLIMITED) // "Unlimited"
+ * ```
+ */
+declare function formatCacheSize(bytes: number): string;
+/**
+ * Current phase of a download operation.
+ */
+type DownloadPhase = "downloading" | "compressing" | "complete" | "error";
+/**
+ * Status of an individual download.
+ */
+interface DownloadStatus {
+    /** Attachment ID */
+    id: string;
+    /** Filename being downloaded */
+    filename: string;
+    /** Current phase */
+    phase: DownloadPhase;
+}
+/**
+ * Current phase of an upload operation.
+ */
+type UploadPhase = "uploading" | "waiting" | "complete" | "error" | "permanent_failure";
+/**
+ * Status of an individual upload.
+ */
+interface UploadStatus {
+    /** Attachment ID */
+    id: string;
+    /** Filename being uploaded */
+    filename: string;
+    /** Current phase */
+    phase: UploadPhase;
+    /** Upload progress (0-100) */
+    progress?: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Why downloads are stopped (if not actively syncing).
+ */
+type AttachmentSyncStatus = "syncing" | "paused" | "cache_full" | "complete";
+/**
+ * Statistics about the attachment sync progress.
+ */
+interface AttachmentSyncStats {
+    /** Number of attachments that have been downloaded */
+    syncedCount: number;
+    /** Total size of synced attachments in bytes */
+    syncedSize: number;
+    /** Number of attachments waiting to be downloaded */
+    pendingCount: number;
+    /** Total expected attachments (synced + pending) */
+    totalExpected: number;
+    /** Maximum cache size in bytes */
+    maxCacheSize: number;
+    /** Current compression quality (0.1 to 1.0) */
+    compressionQuality: number;
+    /** Current sync status */
+    status: AttachmentSyncStatus;
+    /** Whether downloads are paused */
+    isPaused: boolean;
+    /** Whether currently processing downloads */
+    isProcessing: boolean;
+    /** Currently active downloads */
+    activeDownloads: DownloadStatus[];
+    /** Number of uploads waiting to be processed */
+    pendingUploadCount: number;
+    /** Number of permanently failed uploads */
+    failedPermanentCount: number;
+    /** Number of uploads failing > staleDaysThreshold */
+    staleUploadCount: number;
+    /** Currently active uploads */
+    activeUploads: UploadStatus[];
+    /** Number of attachments skipped by downloadFilter */
+    skippedDownloadCount: number;
+}
+/** Row from stats query */
+interface AttachmentStatsRow {
+    state: number;
+    cnt: number;
+    sz: number;
+}
+/** Row for cache file operations */
+interface CacheFileRow {
+    id: string;
+    local_uri: string;
+}
+/** Row for eviction operations */
+interface EvictRow {
+    id: string;
+    local_uri: string;
+    size: number;
+}
+/** Row for cached size queries */
+interface CachedSizeRow {
+    total: number;
+}
+/** Row for ID queries */
+interface IdRow {
+    id: string;
+}
+/**
+ * Alias for PolAttachmentRecord.
+ * Use PolAttachmentRecord for new code. The official @powersync/attachments
+ * AttachmentRecord is exported as OfficialAttachmentRecord.
+ */
+type AttachmentRecord = PolAttachmentRecord;
+
+/**
+ * POL Attachment Queue
+ *
+ * Extends the official @powersync/attachments AbstractAttachmentQueue with
+ * POL-specific features:
+ * - Reactive watchIds callback for attachment ID sources
+ * - Optional skipDownload callback for filtering downloads
+ * - Durable upload queue with exponential backoff retry
+ * - FAILED_PERMANENT state for unrecoverable upload errors
+ * - Image compression integration
+ * - Upload callbacks (onUploadComplete, onUploadFailed)
+ *
+ * @example
+ * ```typescript
+ * const queue = new PolAttachmentQueue({
+ *   powersync: db,
+ *   storage: storageAdapter,
+ *   source: {
+ *     bucket: 'project-assets',
+ *     watchIds: (db, onUpdate) => {
+ *       db.watch('SELECT storagePath FROM photos WHERE storagePath IS NOT NULL', [], {
+ *         onResult: (r) => onUpdate(r.rows._array.map(row => row.storagePath))
+ *       });
+ *     },
+ *     skipDownload: async ({ ids, db }) => {
+ *       // Return IDs to skip downloading
+ *       const videos = await db.getAll('SELECT storagePath FROM photos WHERE mediaType LIKE "video/%"');
+ *       return videos.map(v => v.storagePath);
+ *     }
+ *   },
+ * });
+ *
+ * await queue.init();
+ * ```
+ */
+
+/**
+ * Options for PolAttachmentQueue that extend the official AttachmentQueueOptions.
+ */
+interface PolAttachmentQueueOptions extends AttachmentQueueOptions {
+    platform: PlatformAdapter;
+    remoteStorage: AttachmentStorageAdapter;
+    /** Attachment source configuration with reactive watchIds callback */
+    source: AttachmentSourceConfig;
+    uploadHandler?: UploadHandler;
+    uploadConfig?: Partial<UploadConfig>;
+    /** Download configuration for concurrency tuning */
+    downloadConfig?: Partial<DownloadConfig>;
+    onUploadComplete?: (record: PolAttachmentRecord) => Promise<void>;
+    onUploadFailed?: (record: PolAttachmentRecord, error: Error) => void;
+    compression?: Partial<CompressionConfig>;
+    cache?: Partial<CacheConfig>;
+}
+/**
+ * POL Attachment Queue that extends the official AbstractAttachmentQueue.
+ */
+declare class PolAttachmentQueue extends AbstractAttachmentQueue<PolAttachmentQueueOptions> {
+    private readonly platform;
+    private readonly polLogger;
+    private readonly source;
+    private readonly remoteStorage;
+    private readonly uploadHandler?;
+    private readonly uploadConfig;
+    private readonly downloadConfig;
+    private readonly compressionConfig;
+    private readonly cacheConfig;
+    private _uploadState;
+    private _disposed;
+    private _initialized;
+    private _watchGeneration;
+    private _watchIdsCleanup;
+    private _watchMutex;
+    private _networkListenerCleanup;
+    private _wasConnected;
+    private _progressCallbacks;
+    private _lastNotifyTime;
+    private _notifyTimer;
+    private _cachedStats;
+    private _cachedStatsTimestamp;
+    constructor(options: PolAttachmentQueueOptions);
+    watchUploads(): void;
+    /**
+     * Override parent's expireCache to disable count-based cache eviction.
+     *
+     * The parent implementation deletes SYNCED/ARCHIVED records beyond cacheLimit,
+     * which caused a bug where downloads would reset because:
+     * 1. expireCache deleted records beyond cacheLimit (default 100)
+     * 2. watchIds still emitted those IDs
+     * 3. They got re-created as QUEUED_DOWNLOAD
+     * 4. Downloads restarted in an infinite loop
+     *
+     * Our implementation uses size-based cache limits only (via clearCache/cacheConfig.maxSize).
+     */
+    expireCache(): Promise<void>;
+    /**
+     * Override parent's watchDownloads to use concurrent downloads.
+     *
+     * The parent implementation downloads one file at a time.
+     * This override processes downloads in parallel batches for faster sync.
+     */
+    watchDownloads(): void;
+    /**
+     * Process pending downloads with concurrency control.
+     * Downloads multiple files in parallel based on downloadConfig.concurrency.
+     * Enforces cache size limits after each batch completes.
+     */
+    private _downloadRecordsConcurrent;
+    uploadAttachment(record: {
+        id: string;
+    }): Promise<boolean>;
+    watchAttachmentIds(): Promise<void>;
+    saveToQueue(record: Omit<AttachmentRecord$1, 'timestamp'>): Promise<AttachmentRecord$1>;
+    onAttachmentIdsChange(onUpdate: (ids: string[]) => void): void;
+    downloadRecord(record: AttachmentRecord$1): Promise<boolean>;
+    newAttachmentRecord(record?: Partial<AttachmentRecord$1>): Promise<AttachmentRecord$1>;
+    init(): Promise<void>;
+    /**
+     * Dispose the attachment queue and clean up resources.
+     * This method is synchronous to ensure callers don't need to await it,
+     * but it fires off async cleanup in the background for graceful shutdown.
+     */
+    dispose(): void;
+    /**
+     * Async cleanup that runs in the background after dispose().
+     * Waits for active upload promises to settle gracefully.
+     */
+    private _asyncCleanup;
+    queueUpload(options: {
+        storagePath: string;
+        sourceUri: string;
+        filename: string;
+        mediaType: string;
+        bucketId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    getPendingUploads(): Promise<PolAttachmentRecord[]>;
+    getSoonestRetryTime(): Promise<number | null>;
+    getFailedPermanentUploads(): Promise<PolAttachmentRecord[]>;
+    getStaleUploads(): Promise<PolAttachmentRecord[]>;
+    getSyncedUploadsWithPendingCallback(): Promise<PolAttachmentRecord[]>;
+    clearUploadCallback(id: string): Promise<void>;
+    retryUpload(id: string): Promise<void>;
+    /**
+     * Reset all uploads in QUEUED_UPLOAD state so they retry immediately.
+     * This clears retry counts and errors, allowing uploads to be retried fresh.
+     *
+     * @returns The number of uploads that were reset
+     */
+    resetUploadRetries(): Promise<number>;
+    /**
+     * Trigger immediate retry of uploads WITHOUT resetting their retry count.
+     * This preserves backoff state for truly failing uploads while allowing
+     * uploads that were waiting for network to retry immediately.
+     *
+     * Only affects uploads that:
+     * - Are past their retry time (upload_next_retry_at <= now), OR
+     * - Have no retry time set (upload_next_retry_at IS NULL)
+     *
+     * @returns The number of uploads that will be retried
+     */
+    retryUploads(): Promise<number>;
+    deleteUpload(id: string): Promise<void>;
+    /**
+     * Re-queue an upload for an orphaned attachment.
+     * Use this when a database record exists with a storagePath but the file was never uploaded.
+     *
+     * This handles the case where:
+     * - User took a photo and the database record was created with a storagePath
+     * - The attachment queue record was created but disappeared before upload completed
+     * - The photo shows locally but was never uploaded to storage
+     *
+     * @param options.storagePath - The storage path (e.g., "projectId/fileId.jpg")
+     * @param options.localFileUri - URI to the local file to upload
+     * @param options.mediaType - MIME type of the file
+     * @param options.bucketId - Optional bucket ID for multi-bucket setups
+     * @returns true if upload was queued, false if already exists in valid state
+     */
+    requeueOrphanedUpload(options: {
+        storagePath: string;
+        localFileUri: string;
+        mediaType: string;
+        bucketId?: string;
+    }): Promise<boolean>;
+    getRecord(id: string): Promise<PolAttachmentRecord | null>;
+    getFailedUploads(): Promise<PolAttachmentRecord[]>;
+    retryFailedUpload(id: string): Promise<void>;
+    deleteFailedUpload(id: string): Promise<void>;
+    get activeUploads(): UploadStatus[];
+    pauseUploads(): void;
+    resumeUploads(): void;
+    clearCache(): Promise<void>;
+    cacheLocalFile(storagePath: string, sourceUri: string): Promise<void>;
+    getLocalUriForStoragePath(storagePath: string): Promise<string | null>;
+    /**
+     * Purge attachments by their IDs.
+     * Archives and deletes local files for the specified attachment IDs.
+     * Useful for edge cases where external code needs to force-remove attachments.
+     *
+     * @param ids - Array of attachment IDs to purge
+     */
+    purgeAttachments(ids: string[]): Promise<void>;
+    onProgress(callback: (stats: AttachmentSyncStats) => void): () => void;
+    getStats(): Promise<AttachmentSyncStats>;
+    /**
+     * Repair attachment sizes for synced records that have size=0.
+     * This backfills sizes from the actual file system for existing downloads.
+     * @returns Number of records repaired
+     */
+    repairAttachmentSizes(): Promise<number>;
+    private _getDownloadManagerDeps;
+    private _getUploadManagerDeps;
+    private _getCacheManagerDeps;
+    private _startUploadProcessing;
+    private _createTableIfNotExists;
+    private _migrateUploadColumns;
+    private _invalidateStatsCache;
+    private _getStatus;
+    private _notify;
+}
+/**
+ * Factory function options that combine AttachmentConfig with required runtime dependencies.
+ */
+interface CreateAttachmentQueueOptions extends AttachmentConfig {
+    /** Remote storage adapter for downloading/uploading files */
+    remoteStorage: AttachmentStorageAdapter;
+    /** Upload handler for processing uploads */
+    uploadHandler?: UploadHandler;
+    /** Upload configuration */
+    uploadConfig?: Partial<UploadConfig>;
+    /** Download configuration (concurrency, timeout) */
+    downloadConfig?: Partial<DownloadConfig>;
+    /** Compression configuration */
+    compression?: Partial<CompressionConfig>;
+    /** Cache configuration */
+    cache?: Partial<CacheConfig>;
+}
+declare function createPolAttachmentQueue(powersync: AbstractPowerSyncDatabase, platform: PlatformAdapter, config: CreateAttachmentQueueOptions): PolAttachmentQueue;
+
+export { type AttachmentSourceConfig as A, type BatchFilterContext as B, type CompressionConfig as C, DEFAULT_COMPRESSION_CONFIG as D, type EvictRow as E, type IdRow as I, PolAttachmentQueue as P, type SkipDownloadContext as S, type UploadConfig as U, type WatchConfig as W, type PolAttachmentQueueOptions as a, PolAttachmentState as b, createPolAttachmentQueue as c, type PolAttachmentRecord as d, type AttachmentConfig as e, type AttachmentStorageAdapter as f, DEFAULT_UPLOAD_CONFIG as g, type UploadHandler as h, type DownloadConfig as i, DEFAULT_DOWNLOAD_CONFIG as j, type CacheConfig as k, DEFAULT_CACHE_CONFIG as l, CACHE_SIZE_PRESETS as m, type CacheSizePreset as n, type CacheSizeValue as o, formatCacheSize as p, type DownloadPhase as q, type DownloadStatus as r, type UploadPhase as s, type UploadStatus as t, type AttachmentSyncStatus as u, type AttachmentSyncStats as v, type AttachmentStatsRow as w, type CacheFileRow as x, type CachedSizeRow as y, type AttachmentRecord as z };