@pol-studios/powersync 1.0.6 → 1.0.10

package/dist/attachments/index.d.ts

@@ -1,399 +1,812 @@
-import { A as AbstractPowerSyncDatabase } from '../types-afHtE1U_.js';
-import { PlatformAdapter } from '../platform/index.js';
+import { f as AttachmentStorageAdapter, d as PolAttachmentRecord, h as UploadHandler, U as UploadConfig, t as UploadStatus, k as CacheConfig, W as WatchConfig } from '../pol-attachment-queue-BVAIueoP.js';
+export { e as AttachmentConfig, z as AttachmentRecord, A as AttachmentSourceConfig, w as AttachmentStatsRow, v as AttachmentSyncStats, u as AttachmentSyncStatus, B as BatchFilterContext, m as CACHE_SIZE_PRESETS, x as CacheFileRow, n as CacheSizePreset, o as CacheSizeValue, y as CachedSizeRow, C as CompressionConfig, l as DEFAULT_CACHE_CONFIG, D as DEFAULT_COMPRESSION_CONFIG, j as DEFAULT_DOWNLOAD_CONFIG, g as DEFAULT_UPLOAD_CONFIG, i as DownloadConfig, q as DownloadPhase, r as DownloadStatus, E as EvictRow, I as IdRow, P as PolAttachmentQueue, a as PolAttachmentQueueOptions, b as PolAttachmentState, S as SkipDownloadContext, s as UploadPhase, c as createPolAttachmentQueue, p as formatCacheSize } from '../pol-attachment-queue-BVAIueoP.js';
+import { StorageAdapter, EncodingType, AttachmentRecord } from '@powersync/attachments';
+export { ATTACHMENT_TABLE, AbstractAttachmentQueue, AttachmentState, AttachmentTable, AttachmentTableOptions, AttachmentQueueOptions as BaseAttachmentQueueOptions, DEFAULT_ATTACHMENT_QUEUE_OPTIONS, EncodingType, AttachmentRecord as OfficialAttachmentRecord, StorageAdapter } from '@powersync/attachments';
+import { PlatformAdapter, LoggerAdapter } from '../platform/index.js';
+import { AbstractPowerSyncDatabase } from '@powersync/common';
+export { AbstractPowerSyncDatabase as PowerSyncDBInterface } from '@powersync/common';
+import '../types-CDqWh56B.js';
 
 /**
- * Attachment Queue Types for @pol-studios/powersync
+ * POL Storage Adapter
  *
- * Defines interfaces for the attachment queue system that handles
- * offline file caching with download, compression, and eviction.
- */
-/**
- * State of an attachment in the queue.
- * NOTE: These do NOT match @powersync/attachments enum ordering (values 0-2 differ).
- */
-declare enum AttachmentState {
-    /** Waiting to be downloaded */
-    QUEUED_DOWNLOAD = 0,
-    /** Waiting for initial sync */
-    QUEUED_SYNC = 1,
-    /** Waiting to be uploaded */
-    QUEUED_UPLOAD = 2,
-    /** Fully synced (downloaded or uploaded) */
-    SYNCED = 3,
-    /** Archived (removed from sync but record kept) */
-    ARCHIVED = 4
-}
-/**
- * Record representing an attachment in the queue database.
- */
-interface AttachmentRecord {
-    /** Unique identifier (typically storage path) */
-    id: string;
-    /** Filename for display and type inference */
-    filename: string;
-    /** MIME type of the file */
-    media_type: string;
-    /** Current state in the queue */
-    state: AttachmentState;
-    /** Local file URI (set after download) */
-    local_uri?: string | null;
-    /** File size in bytes */
-    size?: number;
-    /** Timestamp when the attachment was created */
-    timestamp?: number;
-}
-/**
- * Configuration for the source table that contains attachment references.
- * This makes the attachment queue reusable across different tables/projects.
+ * Implements the official @powersync/attachments StorageAdapter interface,
+ * bridging our PlatformAdapter file system and remote storage adapters.
+ *
+ * This adapter combines:
+ * - Local file operations via PlatformAdapter.fileSystem
+ * - Remote upload/download via AttachmentStorageAdapter (e.g., Supabase)
  */
-interface AttachmentSourceConfig {
+
+interface PolStorageAdapterOptions {
     /**
-     * Table name containing attachment references.
-     * @example "EquipmentUnitMediaContent"
+     * Platform adapter for local file system operations.
      */
-    table: string;
+    platform: PlatformAdapter;
     /**
-     * Column containing the storage path / attachment ID.
-     * @example "storagePath"
+     * Remote storage adapter for upload/download operations.
      */
-    idColumn: string;
+    remoteStorage: AttachmentStorageAdapter;
     /**
-     * Column to order by for "newest first" downloads.
-     * Set to null to skip ordering.
-     * @example "takenOn"
+     * Base directory name for attachments within the cache directory.
+     * Defaults to 'attachments'.
      */
-    orderByColumn: string | null;
+    attachmentDirectoryName?: string;
     /**
-     * Optional filter config to exclude attachments from archived/unsynced projects.
-     * When set, the attachment query JOINs through intermediary tables to ensure
-     * only attachments belonging to synced projects are downloaded.
+     * Optional logger for diagnostic messages.
+     * If provided, will log warnings when deprecated code paths are hit.
      */
-    projectFilter?: {
-        /** Foreign key column in the source table (e.g., "equipmentUnitId") */
-        foreignKey: string;
-        /** Intermediary table to JOIN through (e.g., "EquipmentFixtureUnit") */
-        intermediaryTable: string;
-        /** Column in intermediary table that links to ProjectDatabase (e.g., "projectDatabaseId") */
-        projectForeignKey: string;
+    logger?: {
+        warn(message: string, ...args: unknown[]): void;
     };
 }
 /**
- * Interface for attachment storage operations (e.g., Supabase Storage).
+ * Storage adapter that implements the official @powersync/attachments interface.
+ *
+ * Combines local file system operations (via PlatformAdapter) with remote
+ * storage operations (via AttachmentStorageAdapter like Supabase).
+ *
+ * @example
+ * ```typescript
+ * const storageAdapter = new PolStorageAdapter({
+ *   platform: platformAdapter,
+ *   remoteStorage: supabaseStorageAdapter,
+ * });
+ * ```
  */
-interface AttachmentStorageAdapter {
+declare class PolStorageAdapter implements StorageAdapter {
+    private readonly platform;
+    private readonly remoteStorage;
+    private readonly attachmentDirectoryName;
+    private readonly userStorageDirectory;
+    private readonly logger?;
+    constructor(options: PolStorageAdapterOptions);
+    /**
+     * Upload a file to remote storage.
+     */
+    uploadFile(filePath: string, data: ArrayBuffer, options?: {
+        mediaType?: string;
+    }): Promise<void>;
     /**
      * Download a file from remote storage.
-     * @param filePath - The storage path of the file
-     * @returns The file data as a Blob or base64 string
+     *
+     * NOTE: This method implements the official @powersync/attachments StorageAdapter
+     * interface which requires returning Promise<Blob>. For the memory-optimized
+     * file path passthrough, PolAttachmentQueue.downloadRecord() calls
+     * remoteStorage.downloadFile() directly to get the file:// path.
+     *
+     * This method handles base64 string → Blob conversion for backward compatibility.
+     */
+    downloadFile(filePath: string): Promise<Blob>;
+    /**
+     * Write data to a local file.
+     */
+    writeFile(fileUri: string, base64Data: string, options?: {
+        encoding?: EncodingType;
+    }): Promise<void>;
+    /**
+     * Read a local file's contents.
+     */
+    readFile(fileUri: string, options?: {
+        encoding?: EncodingType;
+        mediaType?: string;
+    }): Promise<ArrayBuffer>;
+    /**
+     * Delete a local file.
+     */
+    deleteFile(uri: string, _options?: {
+        filename?: string;
+    }): Promise<void>;
+    /**
+     * Check if a local file exists.
+     */
+    fileExists(fileUri: string): Promise<boolean>;
+    /**
+     * Create a directory (with intermediate directories).
      */
-    downloadFile(filePath: string): Promise<Blob | string>;
+    makeDir(uri: string): Promise<void>;
     /**
-     * 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
+     * Copy a file from source to destination.
      */
-    uploadFile?(filePath: string, data: Blob | string): Promise<void>;
+    copyFile(sourceUri: string, targetUri: string): Promise<void>;
     /**
-     * Delete a file from remote storage (optional).
-     * @param filePath - The storage path of the file
+     * Get the user's storage directory for attachments.
+     * Returns the cache directory path ending with '/'.
      */
-    deleteFile?(filePath: string): Promise<void>;
+    getUserStorageDirectory(): string;
     /**
-     * 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
+     * Warning 8: Optimized base64 encoding using batch processing.
+     * Processes in chunks of 1024 bytes for better performance with large files.
      */
-    resolveBucket?(filePath: string): string;
+    private _arrayBufferToBase64;
+    private _base64ToArrayBuffer;
 }
+
 /**
- * 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;
-}
+ * Attachment State Machine
+ *
+ * Defines state transitions, protected states, and validation logic
+ * for the POL attachment queue system.
+ *
+ * @module attachments/state-machine
+ */
 /**
- * Default compression configuration.
+ * States that represent active upload workflows.
+ * Records in these states should NEVER be demoted to download states.
+ *
+ * This fixes a race condition in the parent AbstractAttachmentQueue.watchAttachmentIds():
+ * - Upload records have `local_uri = null` (they use `upload_source_uri` instead)
+ * - When the CRUD record syncs back, `onAttachmentIdsChange` fires
+ * - Parent checks `record.local_uri == null` → true for uploads
+ * - Parent changes state from QUEUED_UPLOAD to QUEUED_DOWNLOAD
+ * - Upload is abandoned, download fails (file doesn't exist in remote storage yet)
+ *
+ * By protecting these states, we prevent the parent's logic from interfering
+ * with in-progress or queued uploads.
+ *
+ * @see https://github.com/powersync-ja/powersync-js/blob/main/packages/attachments/src/AbstractAttachmentQueue.ts
  */
-declare const DEFAULT_COMPRESSION_CONFIG: CompressionConfig;
+declare const PROTECTED_UPLOAD_STATES: Set<number>;
 /**
- * Configuration for the download engine.
+ * States that indicate a download is pending or in progress.
  */
-interface DownloadConfig {
-    /** Maximum concurrent downloads (default: 50) */
-    concurrency: number;
-    /** Download timeout per file in ms (default: 60000) */
-    timeoutMs: number;
-    /** Retry delay between batches in ms (default: 5000) */
-    retryDelayMs: number;
-}
+declare const PENDING_DOWNLOAD_STATES: Set<number>;
 /**
- * Default download configuration.
+ * States that indicate the attachment is locally available.
  */
-declare const DEFAULT_DOWNLOAD_CONFIG: DownloadConfig;
+declare const LOCALLY_AVAILABLE_STATES: Set<number>;
 /**
- * Configuration for cache management.
+ * Check if a record is in a protected upload state.
+ * Protected states should not be demoted to download states.
  */
-interface CacheConfig {
-    /** Maximum cache size in bytes (default: 5GB) */
-    maxSize: number;
-    /** Stop downloads at this percentage of max (default: 0.95 = 95%) */
-    downloadStopThreshold: number;
-    /** Trigger eviction at this percentage (default: 1.0 = 100%) */
-    evictionTriggerThreshold: number;
-}
+declare function isProtectedUploadState(state: number): boolean;
 /**
- * Default cache configuration.
+ * Check if a record is in a pending download state.
  */
-declare const DEFAULT_CACHE_CONFIG: CacheConfig;
+declare function isPendingDownloadState(state: number): boolean;
 /**
- * Full configuration for the attachment queue.
+ * Check if a record has a locally available file.
  */
-interface AttachmentQueueConfig {
-    /** Source table configuration */
-    source: AttachmentSourceConfig;
-    /** Storage adapter for downloading files */
-    storage: AttachmentStorageAdapter;
-    /** Table name for storing attachment records (default: "photo_attachments") */
-    attachmentTableName?: string;
-    /** Perform initial sync on initialization (default: true) */
-    performInitialSync?: boolean;
-    /** Download configuration */
-    download?: Partial<DownloadConfig>;
-    /** Cache configuration */
-    cache?: Partial<CacheConfig>;
-    /** Compression configuration */
-    compression?: Partial<CompressionConfig>;
-    /**
-     * Called when a download fails.
-     * Return { retry: true } to retry, { retry: false } to skip.
-     */
-    onDownloadError?: (attachment: AttachmentRecord, error: Error) => Promise<{
-        retry: boolean;
+declare function isLocallyAvailable(state: number): boolean;
+/**
+ * Check if a state transition is allowed.
+ * Prevents protected upload states from being demoted to download states.
+ *
+ * @param currentState - The current state of the record
+ * @param newState - The proposed new state
+ * @returns true if the transition is allowed
+ */
+declare function isStateTransitionAllowed(currentState: number, newState: number): boolean;
+/**
+ * Get the appropriate state for a new attachment based on context.
+ *
+ * @param hasLocalUri - Whether the attachment has a local URI
+ * @param hasUploadSourceUri - Whether the attachment has an upload source URI
+ * @param currentState - The current state (if any)
+ * @returns The appropriate state for the attachment
+ */
+declare function determineAttachmentState(hasLocalUri: boolean, hasUploadSourceUri: boolean, currentState?: number): number;
+/**
+ * Validate that a string is a safe SQL identifier.
+ * Prevents SQL injection via config values.
+ *
+ * @param value - The value to validate
+ * @param name - The name of the parameter (for error messages)
+ * @throws Error if the value is not a valid SQL identifier
+ */
+declare function validateSqlIdentifier$1(value: string, name: string): void;
+/**
+ * Build a SQL IN clause with protected upload states excluded.
+ * Used for queries that should not affect upload records.
+ */
+declare function getProtectedStatesInClause(): string;
+/**
+ * Build a SQL condition that excludes protected upload states.
+ */
+declare function getExcludeProtectedStatesCondition(stateColumn?: string): string;
+
+/**
+ * Download Manager
+ *
+ * Handles download-related logic including batch filtering,
+ * download filter application, and download record processing.
+ *
+ * @module attachments/download-manager
+ */
+
+/**
+ * Dependencies required by the download manager.
+ */
+interface DownloadManagerDeps {
+    /** PowerSync database instance */
+    powersync: AbstractPowerSyncDatabase;
+    /** Platform adapter for file system operations */
+    platform: PlatformAdapter;
+    /** Logger adapter */
+    logger: LoggerAdapter;
+    /** Remote storage adapter for downloading files */
+    remoteStorage: AttachmentStorageAdapter;
+    /** Storage adapter with file operations */
+    storage: {
+        fileExists(uri: string): Promise<boolean>;
+        writeFile(uri: string, data: string, options?: {
+            encoding?: EncodingType;
+        }): Promise<void>;
+        makeDir(uri: string): Promise<void>;
+        copyFile(src: string, dest: string): Promise<void>;
+    };
+    /** Attachment table name */
+    tableName: string;
+    /** Function to get local URI from local path */
+    getLocalUri: (localPath: string) => string;
+    /** Function to get local file path suffix */
+    getLocalFilePathSuffix: (filename: string) => string;
+    /** Function to update a record */
+    update: (record: AttachmentRecord) => Promise<void>;
+    /** Whether downloads are enabled */
+    downloadAttachments?: boolean;
+    /** Callback when download errors occur */
+    onDownloadError?: (record: AttachmentRecord, error: Error) => Promise<{
+        retry?: boolean;
     }>;
-    /**
-     * Called when sync progress changes.
-     */
-    onProgress?: (stats: AttachmentSyncStats) => void;
+    /** Function to notify progress updates */
+    notify: (immediate: boolean) => void;
+    /** Function to invalidate stats cache */
+    invalidateStatsCache: () => void;
 }
 /**
- * Current phase of a download operation.
+ * Convert a Blob to ArrayBuffer with fallback for React Native.
+ *
+ * Blob.arrayBuffer() is a web API not available in React Native's Hermes engine.
+ * Falls back to FileReader.readAsArrayBuffer() which works better than readAsDataURL()
+ * in React Native (readAsDataURL hangs but readAsArrayBuffer typically works).
  */
-type DownloadPhase = 'downloading' | 'compressing' | 'complete' | 'error';
+declare function blobToArrayBuffer(blob: Blob): Promise<ArrayBuffer>;
 /**
- * Status of an individual download.
+ * Download a single attachment record.
+ *
+ * Avoids FileReader.readAsDataURL() which hangs in React Native.
+ * The parent implementation uses FileReader to convert Blob to base64,
+ * but FileReader hangs indefinitely in React Native environments.
+ * This override writes the downloaded file directly to the file system
+ * using platform-native methods.
+ *
+ * Note: Filtering is handled by skipDownload callback in the queue.
  */
-interface DownloadStatus {
-    /** Attachment ID */
-    id: string;
-    /** Filename being downloaded */
-    filename: string;
-    /** Current phase */
-    phase: DownloadPhase;
-}
+declare function downloadRecord(deps: DownloadManagerDeps, record: AttachmentRecord): Promise<boolean>;
+
+/**
+ * Upload Manager
+ *
+ * Handles upload processing, retry scheduling, error handling,
+ * and upload lifecycle management.
+ *
+ * @module attachments/upload-manager
+ */
+
 /**
- * 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[];
+ * Dependencies required by the upload manager.
+ */
+interface UploadManagerDeps {
+    /** PowerSync database instance */
+    powersync: AbstractPowerSyncDatabase;
+    /** Platform adapter for file system operations */
+    platform: PlatformAdapter;
+    /** Logger adapter */
+    logger: LoggerAdapter;
+    /** Attachment table name */
+    tableName: string;
+    /** Upload handler for uploading files */
+    uploadHandler?: UploadHandler;
+    /** Upload configuration */
+    uploadConfig: UploadConfig;
+    /** Callback when upload completes */
+    onUploadComplete?: (record: PolAttachmentRecord) => Promise<void>;
+    /** Callback when upload fails permanently */
+    onUploadFailed?: (record: PolAttachmentRecord, error: Error) => void;
+    /** Function to notify progress updates */
+    notify: (immediate: boolean) => void;
 }
-/** Row from stats query */
-interface AttachmentStatsRow {
-    state: number;
-    cnt: number;
-    sz: number;
+/**
+ * State for the upload manager.
+ */
+interface UploadManagerState {
+    /** Whether upload processing is active */
+    processing: boolean;
+    /** Whether uploads are paused */
+    paused: boolean;
+    /** Abort controller for cancellation */
+    abortController: AbortController;
+    /** Map of active uploads */
+    activeUploads: Map<string, UploadStatus>;
+    /** Set of active upload promises for cleanup during dispose */
+    activePromises: Set<Promise<void>>;
 }
-/** Row for cache file operations */
-interface CacheFileRow {
-    id: string;
-    local_uri: string;
+/**
+ * Check if an error is permanent (should not retry).
+ */
+declare function isPermanentError(error: Error): boolean;
+/**
+ * Extract HTTP status code from error message.
+ * Uses specific patterns to avoid false positives from numbers in other contexts.
+ */
+declare function extractErrorCode(error: Error): string | undefined;
+/**
+ * Get pending uploads that need retry.
+ */
+declare function getPendingUploads(powersync: AbstractPowerSyncDatabase, tableName: string): Promise<PolAttachmentRecord[]>;
+/**
+ * Get the soonest retry time for all uploads currently in backoff.
+ * Returns null if there are no uploads waiting for retry.
+ */
+declare function getSoonestRetryTime(powersync: AbstractPowerSyncDatabase, tableName: string): Promise<number | null>;
+/**
+ * Get uploads that have permanently failed.
+ */
+declare function getFailedPermanentUploads(powersync: AbstractPowerSyncDatabase, tableName: string): Promise<PolAttachmentRecord[]>;
+/**
+ * Get stale uploads (failing for > staleDaysThreshold).
+ */
+declare function getStaleUploads(powersync: AbstractPowerSyncDatabase, tableName: string, staleDaysThreshold: number): Promise<PolAttachmentRecord[]>;
+/**
+ * Get SYNCED uploads that have pending onComplete callbacks.
+ */
+declare function getSyncedUploadsWithPendingCallback(powersync: AbstractPowerSyncDatabase, tableName: string): Promise<PolAttachmentRecord[]>;
+/**
+ * Clear the onCompleteCallback flag from a record's metadata.
+ */
+declare function clearUploadCallback(powersync: AbstractPowerSyncDatabase, tableName: string, id: string, uploadMetadata?: string | null): Promise<void>;
+/**
+ * Mark an upload as synced (complete).
+ */
+declare function markUploadSynced(deps: UploadManagerDeps, record: PolAttachmentRecord): Promise<void>;
+/**
+ * Mark an upload as permanently failed.
+ */
+declare function markUploadPermanentFailure(deps: UploadManagerDeps, record: PolAttachmentRecord, errorMessage: string, errorCode?: string): Promise<void>;
+/**
+ * Schedule an upload retry with exponential backoff.
+ */
+declare function scheduleUploadRetry(deps: UploadManagerDeps, record: PolAttachmentRecord, error: Error): Promise<void>;
+/**
+ * Upload a single record.
+ */
+declare function uploadOne(deps: UploadManagerDeps, state: UploadManagerState, record: PolAttachmentRecord): Promise<void>;
+/**
+ * Start the upload processing loop.
+ */
+declare function startUploadProcessing(deps: UploadManagerDeps, state: UploadManagerState): Promise<void>;
+/**
+ * Create initial upload manager state.
+ */
+declare function createUploadManagerState(): UploadManagerState;
+/**
+ * Create upload manager dependencies with defaults.
+ */
+declare function createUploadManagerDeps(partial: Omit<UploadManagerDeps, 'uploadConfig'> & {
+    uploadConfig?: Partial<UploadConfig>;
+}): UploadManagerDeps;
+
+/**
+ * Cache Manager
+ *
+ * Handles cache eviction, cleanup logic, and cache management utilities.
+ *
+ * @module attachments/cache-manager
+ */
+
+/**
+ * Ensure a path has the `file://` URI prefix.
+ * Used to standardize URI format throughout the attachment system.
+ */
+declare function ensureFileUri(path: string): string;
+/**
+ * Strip the `file://` prefix from a URI to get the raw file path.
+ * Used when APIs require raw paths instead of URIs.
+ */
+declare function stripFileUri(uri: string): string;
+/**
+ * Dependencies required by the cache manager.
+ */
+interface CacheManagerDeps {
+    /** PowerSync database instance */
+    powersync: AbstractPowerSyncDatabase;
+    /** Platform adapter for file system operations */
+    platform: PlatformAdapter;
+    /** Logger adapter */
+    logger: LoggerAdapter;
+    /** Attachment table name */
+    tableName: string;
+    /** Cache configuration */
+    cacheConfig: CacheConfig;
+    /** Function to get local URI from local path */
+    getLocalUri: (localPath: string) => string;
+    /** Function to notify progress updates */
+    notify: (immediate: boolean) => void;
+    /** Function to invalidate stats cache */
+    invalidateStatsCache: () => void;
 }
-/** Row for eviction operations */
-interface EvictRow {
+/**
+ * Get total size of cached files.
+ */
+declare function getCachedSize(powersync: AbstractPowerSyncDatabase, tableName: string): Promise<number>;
+/**
+ * Get files eligible for eviction, ordered by timestamp (oldest first).
+ */
+declare function getEvictionCandidates(powersync: AbstractPowerSyncDatabase, tableName: string): Promise<Array<{
     id: string;
     local_uri: string;
     size: number;
-}
-/** Row for cached size queries */
-interface CachedSizeRow {
-    total: number;
-}
-/** Row for ID queries */
-interface IdRow {
-    id: string;
-}
+}>>;
+/**
+ * Enforce the cache size limit by evicting oldest files.
+ *
+ * This function checks if the current cache size exceeds `cacheConfig.maxSize`.
+ * If so, it evicts files (oldest first by timestamp) until the cache is below
+ * the max size. Evicted files have their `local_uri` cleared and state reset
+ * to `QUEUED_DOWNLOAD` so they can be re-downloaded later if needed.
+ *
+ * @returns Object with eviction stats: { evictedCount, freedBytes }
+ */
+declare function enforceCacheLimit(deps: CacheManagerDeps): Promise<{
+    evictedCount: number;
+    freedBytes: number;
+}>;
+/**
+ * Check if cache is near capacity (at downloadStopThreshold).
+ * Used to decide whether to skip starting new downloads.
+ *
+ * @returns true if cache is at or above the download stop threshold
+ */
+declare function isCacheNearCapacity(deps: CacheManagerDeps): Promise<boolean>;
+/**
+ * Clear all cached files and re-queue for download.
+ * Preserves upload records (QUEUED_UPLOAD, FAILED_PERMANENT).
+ */
+declare function clearCache(deps: CacheManagerDeps): Promise<void>;
+/**
+ * Cache a local file into the attachment cache.
+ * Used to cache uploaded files to avoid redundant downloads.
+ */
+declare function cacheLocalFile(deps: CacheManagerDeps, storagePath: string, sourceUri: string): Promise<void>;
+/**
+ * Get the local file URI for a storage path.
+ * Checks both downloaded files (SYNCED state) and pending uploads (QUEUED_UPLOAD state).
+ */
+declare function getLocalUriForStoragePath(deps: CacheManagerDeps, storagePath: string, storage: {
+    fileExists(uri: string): Promise<boolean>;
+}): Promise<string | null>;
+/**
+ * Copy source file to managed cache for durable uploads.
+ */
+declare function copyToManagedCache(platform: PlatformAdapter, logger: LoggerAdapter, sourceUri: string, storagePath: string): Promise<string>;
+/**
+ * Create cache manager dependencies with defaults.
+ */
+declare function createCacheManagerDeps(partial: Omit<CacheManagerDeps, 'cacheConfig'> & {
+    cacheConfig?: Partial<CacheConfig>;
+}): CacheManagerDeps;
 
 /**
- * Attachment Queue for @pol-studios/powersync
+ * Query Builder for Attachment Watch Queries
  *
- * Platform-agnostic attachment queue that handles:
- * - Parallel downloads with configurable concurrency
- * - Cache management with eviction
- * - Image compression
- * - Pause/resume functionality
- * - Progress tracking
+ * Generates SQL queries from WatchConfig objects.
+ * Provides type-safe query generation without raw SQL strings.
  */
 
 /**
- * Platform-agnostic attachment queue for offline file caching.
+ * Validates that a string is a safe SQL identifier.
+ * Throws an error if the identifier is invalid or potentially dangerous.
+ *
+ * @param identifier - The identifier to validate
+ * @param context - Description of where this identifier is used (for error messages)
+ * @throws Error if identifier is invalid
+ */
+declare function validateSqlIdentifier(identifier: string, context: string): void;
+/**
+ * Validates a WHERE clause fragment for basic safety.
+ * Note: This is a best-effort validation. Complex WHERE clauses should be reviewed.
+ *
+ * @param whereClause - The WHERE clause fragment to validate
+ * @throws Error if the clause contains dangerous patterns
+ */
+declare function validateWhereClause(whereClause: string): void;
+/**
+ * Build a SQL watch query from a WatchConfig.
+ *
+ * Generates a SELECT statement that:
+ * - Selects the ID column (aliased as `id`)
+ * - Optionally selects additional columns
+ * - Applies an optional WHERE clause
+ * - Optionally orders by a column
+ *
+ * @param config - The WatchConfig to build a query from
+ * @returns SQL query string
  *
  * @example
  * ```typescript
- * const queue = new AttachmentQueue({
- *   powersync: db,
- *   platform: platformAdapter,
- *   config: {
- *     source: {
- *       table: 'EquipmentUnitMediaContent',
- *       idColumn: 'storagePath',
- *       orderByColumn: 'takenOn',
- *     },
- *     storage: storageAdapter,
- *   },
+ * const query = buildWatchQuery({
+ *   table: 'EquipmentUnitMediaContent',
+ *   idColumn: 'storagePath',
+ *   selectColumns: ['equipmentUnitId', 'takenOn'],
+ *   where: 'storagePath IS NOT NULL',
+ *   orderBy: { column: 'takenOn', direction: 'DESC' },
  * });
  *
- * await queue.init();
+ * // Result:
+ * // SELECT storagePath AS id, equipmentUnitId, takenOn
+ * // FROM EquipmentUnitMediaContent
+ * // WHERE storagePath IS NOT NULL
+ * // ORDER BY takenOn DESC
  * ```
  */
-declare class AttachmentQueue {
-    private readonly powersync;
-    private readonly platform;
-    private readonly config;
-    private readonly logger;
-    private readonly tableName;
-    private readonly concurrency;
-    private readonly downloadTimeoutMs;
-    private readonly retryDelayMs;
-    private readonly downloadStopThreshold;
-    private readonly evictionTriggerThreshold;
-    private _initialized;
-    private _paused;
-    private _processing;
-    private _cacheFull;
-    private _resumeRequested;
-    private _maxCacheSize;
-    private _compressionQuality;
-    private _abort;
-    private _downloads;
-    private _cachedSize;
-    private _cachedSizeTimestamp;
-    private _cachedStats;
-    private _cachedStatsTimestamp;
-    private _lastNotifyTime;
-    private _notifyTimer;
-    private _progressCallbacks;
-    private _watcherInterval;
-    constructor(options: {
-        powersync: AbstractPowerSyncDatabase;
-        platform: PlatformAdapter;
-        config: AttachmentQueueConfig;
-    });
-    /**
-     * Initialize the attachment queue.
-     * Creates the attachment table if needed and starts watching for downloads.
-     */
-    init(): Promise<void>;
-    /**
-     * Dispose the attachment queue.
-     */
-    dispose(): void;
-    /**
-     * Subscribe to real-time progress updates.
-     * Returns an unsubscribe function.
-     */
-    onProgress(callback: (stats: AttachmentSyncStats) => void): () => void;
-    /** Whether downloads are paused */
-    get paused(): boolean;
-    /** Whether currently processing downloads */
-    get processing(): boolean;
-    /**
-     * Set the maximum cache size.
-     */
-    setMaxCacheSize(bytes: number): Promise<void>;
-    /**
-     * Set the compression quality (0.1 to 1.0).
-     */
-    setCompressionQuality(quality: number): void;
-    /** Get the current compression quality */
-    getCompressionQuality(): number;
-    /**
-     * Pause downloads.
-     */
-    pause(): void;
-    /**
-     * Resume downloads.
-     */
-    resume(): void;
-    /**
-     * Get current sync statistics.
-     */
-    getStats(): Promise<AttachmentSyncStats>;
-    /**
-     * Clear all cached files and re-queue for download.
-     */
-    clearCache(): Promise<void>;
-    /**
-     * Get an attachment record by ID.
-     */
-    getRecord(id: string): Promise<AttachmentRecord | null>;
-    /**
-     * Get the local file URI for an attachment.
-     */
-    getLocalUri(localPath: string): string;
-    /**
-     * Cache a local file (e.g. one just uploaded) into the attachment cache.
-     * This avoids a redundant download by copying the source file directly
-     * into the cache directory and marking it as SYNCED.
-     */
-    cacheLocalFile(storagePath: string, sourceUri: string): Promise<void>;
-    private _startDownloadWatcher;
-    private _syncAttachmentIds;
-    private _startDownloads;
-    private _downloadOne;
-    private _batchUpdateSizes;
-    private _getIdsToDownload;
-    private _evictIfNeeded;
-    private _compressImage;
-    private _isImage;
-    private _getStatus;
-    private _getCachedSizeWithCache;
-    private _orderByNewest;
-    private _sleep;
-    private _withTimeout;
-    private _blobToBase64;
-    private _notify;
+declare function buildWatchQuery(config: WatchConfig): string;
+/**
+ * Build a simpler ID-only watch query.
+ * Use this when you only need IDs without additional columns.
+ *
+ * @param config - The WatchConfig to build a query from
+ * @returns SQL query string that selects only IDs
+ *
+ * @example
+ * ```typescript
+ * const query = buildIdOnlyWatchQuery({
+ *   table: 'EquipmentUnitMediaContent',
+ *   idColumn: 'storagePath',
+ *   where: 'storagePath IS NOT NULL',
+ * });
+ *
+ * // Result:
+ * // SELECT storagePath AS id
+ * // FROM EquipmentUnitMediaContent
+ * // WHERE storagePath IS NOT NULL AND storagePath != ''
+ * ```
+ */
+declare function buildIdOnlyWatchQuery(config: WatchConfig): string;
+/**
+ * Build a query to fetch records with their IDs and additional columns.
+ * Used for populating the BatchFilterContext.records map.
+ *
+ * @param config - The WatchConfig to build a query from
+ * @param ids - Optional list of IDs to filter to (for efficiency)
+ * @returns SQL query string and parameters
+ *
+ * @example
+ * ```typescript
+ * const { query, params } = buildRecordFetchQuery(
+ *   {
+ *     table: 'EquipmentUnitMediaContent',
+ *     idColumn: 'storagePath',
+ *     selectColumns: ['equipmentUnitId'],
+ *   },
+ *   ['path/to/file1.jpg', 'path/to/file2.jpg']
+ * );
+ * ```
+ */
+declare function buildRecordFetchQuery(config: WatchConfig, ids?: string[]): {
+    query: string;
+    params: unknown[];
+};
+/**
+ * Convert WatchConfig to the legacy AttachmentSourceConfig format.
+ * Useful during migration to maintain backwards compatibility.
+ *
+ * @param watchConfig - The new WatchConfig
+ * @returns Legacy AttachmentSourceConfig
+ */
+declare function watchConfigToSourceConfig(watchConfig: WatchConfig): {
+    table: string;
+    idColumn: string;
+    orderByColumn?: string | null;
+};
+
+/**
+ * Migration Utilities for @pol-studios/powersync Attachments
+ *
+ * This module provides utilities for migrating from the old attachment API
+ * to the new callback-based API. It includes:
+ *
+ * - State mapping constants for old → new state transitions
+ * - `migrateAttachmentState()` for converting state values
+ * - Validation helpers for migration safety
+ *
+ * @example
+ * ```typescript
+ * import { migrateAttachmentState, isValidAttachmentState } from '@pol-studios/powersync/attachments';
+ *
+ * // Migrate a single state value
+ * const newState = migrateAttachmentState(oldState);
+ *
+ * // Validate before migration
+ * if (isValidAttachmentState(value)) {
+ *   const migrated = migrateAttachmentState(value);
+ * }
+ * ```
+ */
+/**
+ * Maps old state values to new state values.
+ *
+ * The official @powersync/attachments AttachmentState enum has values 0-4:
+ *   QUEUED_SYNC=0, QUEUED_UPLOAD=1, QUEUED_DOWNLOAD=2, SYNCED=3, ARCHIVED=4
+ *
+ * POL extensions add:
+ *   FAILED_PERMANENT=5, DOWNLOAD_SKIPPED=6
+ *
+ * For migration purposes, most states map 1:1. The mapping exists to:
+ * 1. Document the relationship between old and new states
+ * 2. Provide a clear upgrade path for custom state handling code
+ * 3. Allow future state reorganization if needed
+ */
+declare const STATE_MAPPING: ReadonlyMap<number, number>;
+/**
+ * Human-readable names for attachment states.
+ * Useful for logging and debugging during migration.
+ */
+declare const STATE_NAMES: ReadonlyMap<number, string>;
+/**
+ * All valid state values (official + POL extensions).
+ */
+declare const VALID_STATES: ReadonlySet<number>;
+/**
+ * States that indicate an active upload workflow.
+ * Records in these states should not be migrated to download states.
+ */
+declare const UPLOAD_WORKFLOW_STATES: ReadonlySet<number>;
+/**
+ * States that indicate an active download workflow.
+ */
+declare const DOWNLOAD_WORKFLOW_STATES: ReadonlySet<number>;
+/**
+ * Terminal states (no further processing needed).
+ */
+declare const TERMINAL_STATES: ReadonlySet<number>;
+/**
+ * Migrates an attachment state from the old API to the new API.
+ *
+ * Currently, this is a 1:1 mapping since the state values haven't changed.
+ * This function exists to:
+ * 1. Provide a clear migration path for apps using custom state handling
+ * 2. Document the state relationship
+ * 3. Allow future state reorganization without breaking existing code
+ *
+ * @param oldState - The state value from the old API
+ * @returns The corresponding state value in the new API
+ * @throws Error if the state value is invalid
+ *
+ * @example
+ * ```typescript
+ * import { migrateAttachmentState } from '@pol-studios/powersync/attachments';
+ *
+ * // Migrate a record's state
+ * const newState = migrateAttachmentState(record.state);
+ *
+ * // Migrate with fallback for unknown states
+ * const safeState = isValidAttachmentState(record.state)
+ *   ? migrateAttachmentState(record.state)
+ *   : PolAttachmentState.QUEUED_SYNC;
+ * ```
+ */
+declare function migrateAttachmentState(oldState: number): number;
+/**
+ * Safely migrates an attachment state with a fallback.
+ *
+ * Unlike `migrateAttachmentState`, this function never throws.
+ * Invalid states are mapped to the provided fallback.
+ *
+ * @param oldState - The state value from the old API
+ * @param fallback - State to use if oldState is invalid (default: QUEUED_SYNC)
+ * @returns The corresponding state value in the new API, or the fallback
+ *
+ * @example
+ * ```typescript
+ * // Safely migrate with QUEUED_SYNC as fallback
+ * const state = migrateAttachmentStateSafe(unknownValue);
+ *
+ * // Use custom fallback
+ * const state = migrateAttachmentStateSafe(unknownValue, PolAttachmentState.ARCHIVED);
+ * ```
+ */
+declare function migrateAttachmentStateSafe(oldState: number, fallback?: number): number;
+/**
+ * Checks if a value is a valid attachment state.
+ *
+ * @param value - The value to check
+ * @returns true if the value is a valid attachment state
+ *
+ * @example
+ * ```typescript
+ * if (isValidAttachmentState(record.state)) {
+ *   // Safe to use record.state
+ * } else {
+ *   console.warn(`Invalid state: ${record.state}`);
+ * }
+ * ```
+ */
+declare function isValidAttachmentState(value: unknown): value is number;
+/**
+ * Checks if a state represents an upload workflow.
+ *
+ * Records in upload workflow states should not be demoted to download states.
+ *
+ * @param state - The state to check
+ * @returns true if the state is part of an upload workflow
+ */
+declare function isUploadWorkflowState(state: number): boolean;
+/**
+ * Checks if a state represents a download workflow.
+ *
+ * @param state - The state to check
+ * @returns true if the state is part of a download workflow
+ */
+declare function isDownloadWorkflowState(state: number): boolean;
+/**
+ * Checks if a state is terminal (no further processing needed).
+ *
+ * @param state - The state to check
+ * @returns true if the state is terminal
+ */
+declare function isTerminalState(state: number): boolean;
+/**
+ * Gets the human-readable name of a state.
+ *
+ * @param state - The state value
+ * @returns The state name, or "UNKNOWN" for invalid states
+ *
+ * @example
+ * ```typescript
+ * console.log(`State: ${getStateName(record.state)}`); // "State: SYNCED"
+ * ```
+ */
+declare function getStateName(state: number): string;
+/**
+ * Statistics about a batch migration.
+ */
+interface MigrationStats {
+    /** Total records processed */
+    total: number;
+    /** Records successfully migrated */
+    migrated: number;
+    /** Records with invalid states (used fallback) */
+    invalid: number;
+    /** Breakdown by state */
+    byState: Map<number, number>;
 }
+/**
+ * Creates empty migration stats.
+ */
+declare function createMigrationStats(): MigrationStats;
+/**
+ * Records a migration result in the stats.
+ *
+ * @param stats - The stats object to update
+ * @param oldState - The original state
+ * @param newState - The migrated state
+ * @param wasValid - Whether the original state was valid
+ */
+declare function recordMigration(stats: MigrationStats, oldState: number, newState: number, wasValid: boolean): void;
+/**
+ * Formats migration stats as a human-readable summary.
+ *
+ * @param stats - The stats to format
+ * @returns A formatted string summary
+ *
+ * @example
+ * ```typescript
+ * const stats = createMigrationStats();
+ * // ... process records ...
+ * console.log(formatMigrationStats(stats));
+ * // Output:
+ * // Migration Summary:
+ * //   Total: 100
+ * //   Migrated: 98
+ * //   Invalid (used fallback): 2
+ * //   By State:
+ * //     SYNCED: 50
+ * //     QUEUED_DOWNLOAD: 30
+ * //     QUEUED_UPLOAD: 18
+ * //     QUEUED_SYNC: 2
+ * ```
+ */
+declare function formatMigrationStats(stats: MigrationStats): string;
 
-export { AttachmentQueue, type AttachmentQueueConfig, type AttachmentRecord, type AttachmentSourceConfig, AttachmentState, type AttachmentStatsRow, type AttachmentStorageAdapter, type AttachmentSyncStats, type AttachmentSyncStatus, type CacheConfig, type CacheFileRow, type CachedSizeRow, type CompressionConfig, DEFAULT_CACHE_CONFIG, DEFAULT_COMPRESSION_CONFIG, DEFAULT_DOWNLOAD_CONFIG, type DownloadConfig, type DownloadPhase, type DownloadStatus, type EvictRow, type IdRow };
+export { AttachmentStorageAdapter, CacheConfig, type CacheManagerDeps, DOWNLOAD_WORKFLOW_STATES, type DownloadManagerDeps, LOCALLY_AVAILABLE_STATES, type MigrationStats, PENDING_DOWNLOAD_STATES, PROTECTED_UPLOAD_STATES, PolAttachmentRecord, PolStorageAdapter, type PolStorageAdapterOptions, STATE_MAPPING, STATE_NAMES, TERMINAL_STATES, UPLOAD_WORKFLOW_STATES, UploadConfig, UploadHandler, type UploadManagerDeps, type UploadManagerState, UploadStatus, VALID_STATES, WatchConfig, blobToArrayBuffer, buildIdOnlyWatchQuery, buildRecordFetchQuery, buildWatchQuery, cacheLocalFile, clearCache, clearUploadCallback, copyToManagedCache, createCacheManagerDeps, createMigrationStats, createUploadManagerDeps, createUploadManagerState, determineAttachmentState, downloadRecord, enforceCacheLimit, ensureFileUri, extractErrorCode, formatMigrationStats, getCachedSize, getEvictionCandidates, getExcludeProtectedStatesCondition, getFailedPermanentUploads, getLocalUriForStoragePath, getPendingUploads, getProtectedStatesInClause, getSoonestRetryTime, getStaleUploads, getStateName, getSyncedUploadsWithPendingCallback, isCacheNearCapacity, isDownloadWorkflowState, isLocallyAvailable, isPendingDownloadState, isPermanentError, isProtectedUploadState, isStateTransitionAllowed, isTerminalState, isUploadWorkflowState, isValidAttachmentState, markUploadPermanentFailure, markUploadSynced, migrateAttachmentState, migrateAttachmentStateSafe, recordMigration, scheduleUploadRetry, startUploadProcessing, stripFileUri, uploadOne, validateSqlIdentifier, validateSqlIdentifier$1 as validateSqlIdentifierFromStateMachine, validateWhereClause, watchConfigToSourceConfig };