@pol-studios/powersync 1.0.7 → 1.0.10

package/dist/attachments/index.d.ts

@@ -1,9 +1,10 @@
-import { e as AttachmentStorageAdapter } from '../pol-attachment-queue-C7YNXXhK.js';
-export { t as AttachmentRecord, A as AttachmentSourceConfig, q as AttachmentStatsRow, p as AttachmentSyncStats, o as AttachmentSyncStatus, h as CacheConfig, r as CacheFileRow, s as CachedSizeRow, C as CompressionConfig, i as DEFAULT_CACHE_CONFIG, D as DEFAULT_COMPRESSION_CONFIG, f as DEFAULT_UPLOAD_CONFIG, k as DownloadPhase, l as DownloadStatus, E as EvictRow, I as IdRow, P as PolAttachmentQueue, j as PolAttachmentQueueConfig, a as PolAttachmentQueueOptions, d as PolAttachmentRecord, b as PolAttachmentState, U as UploadConfig, g as UploadHandler, m as UploadPhase, n as UploadStatus, c as createPolAttachmentQueue } from '../pol-attachment-queue-C7YNXXhK.js';
-import { StorageAdapter, EncodingType } from '@powersync/attachments';
+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 } from '../platform/index.js';
-import '@powersync/common';
+import { PlatformAdapter, LoggerAdapter } from '../platform/index.js';
+import { AbstractPowerSyncDatabase } from '@powersync/common';
+export { AbstractPowerSyncDatabase as PowerSyncDBInterface } from '@powersync/common';
 import '../types-CDqWh56B.js';
 
 /**
@@ -31,6 +32,13 @@ interface PolStorageAdapterOptions {
      * Defaults to 'attachments'.
      */
     attachmentDirectoryName?: string;
+    /**
+     * Optional logger for diagnostic messages.
+     * If provided, will log warnings when deprecated code paths are hit.
+     */
+    logger?: {
+        warn(message: string, ...args: unknown[]): void;
+    };
 }
 /**
  * Storage adapter that implements the official @powersync/attachments interface.
@@ -51,6 +59,7 @@ declare class PolStorageAdapter implements StorageAdapter {
     private readonly remoteStorage;
     private readonly attachmentDirectoryName;
     private readonly userStorageDirectory;
+    private readonly logger?;
     constructor(options: PolStorageAdapterOptions);
     /**
      * Upload a file to remote storage.
@@ -60,6 +69,13 @@ declare class PolStorageAdapter implements StorageAdapter {
     }): Promise<void>;
     /**
      * Download a file from remote storage.
+     *
+     * 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>;
     /**
@@ -106,4 +122,691 @@ declare class PolStorageAdapter implements StorageAdapter {
     private _base64ToArrayBuffer;
 }
 
-export { AttachmentStorageAdapter, PolStorageAdapter, type PolStorageAdapterOptions };
+/**
+ * Attachment State Machine
+ *
+ * Defines state transitions, protected states, and validation logic
+ * for the POL attachment queue system.
+ *
+ * @module attachments/state-machine
+ */
+/**
+ * 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 PROTECTED_UPLOAD_STATES: Set<number>;
+/**
+ * States that indicate a download is pending or in progress.
+ */
+declare const PENDING_DOWNLOAD_STATES: Set<number>;
+/**
+ * States that indicate the attachment is locally available.
+ */
+declare const LOCALLY_AVAILABLE_STATES: Set<number>;
+/**
+ * Check if a record is in a protected upload state.
+ * Protected states should not be demoted to download states.
+ */
+declare function isProtectedUploadState(state: number): boolean;
+/**
+ * Check if a record is in a pending download state.
+ */
+declare function isPendingDownloadState(state: number): boolean;
+/**
+ * Check if a record has a locally available file.
+ */
+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;
+    }>;
+    /** Function to notify progress updates */
+    notify: (immediate: boolean) => void;
+    /** Function to invalidate stats cache */
+    invalidateStatsCache: () => void;
+}
+/**
+ * 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).
+ */
+declare function blobToArrayBuffer(blob: Blob): Promise<ArrayBuffer>;
+/**
+ * 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.
+ */
+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
+ */
+
+/**
+ * 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;
+}
+/**
+ * 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>>;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}>>;
+/**
+ * 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;
+
+/**
+ * Query Builder for Attachment Watch Queries
+ *
+ * Generates SQL queries from WatchConfig objects.
+ * Provides type-safe query generation without raw SQL strings.
+ */
+
+/**
+ * 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 query = buildWatchQuery({
+ *   table: 'EquipmentUnitMediaContent',
+ *   idColumn: 'storagePath',
+ *   selectColumns: ['equipmentUnitId', 'takenOn'],
+ *   where: 'storagePath IS NOT NULL',
+ *   orderBy: { column: 'takenOn', direction: 'DESC' },
+ * });
+ *
+ * // Result:
+ * // SELECT storagePath AS id, equipmentUnitId, takenOn
+ * // FROM EquipmentUnitMediaContent
+ * // WHERE storagePath IS NOT NULL
+ * // ORDER BY takenOn DESC
+ * ```
+ */
+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 { 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 };