@pol-studios/powersync 1.0.7 → 1.0.10

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

@@ -1,676 +0,0 @@
-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
-}
-/**
- * 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;
-}
-/**
- * Configuration for the source table that contains attachment references.
- * This makes the attachment queue reusable across different tables/projects.
- */
-interface AttachmentSourceConfig {
-    /**
-     * Table name containing attachment references.
-     * @example "EquipmentUnitMediaContent"
-     */
-    table: string;
-    /**
-     * Column containing the storage path / attachment ID.
-     * @example "storagePath"
-     */
-    idColumn: string;
-    /**
-     * Column to order by for "newest first" downloads.
-     * Set to null to skip ordering.
-     * @example "takenOn"
-     */
-    orderByColumn?: string | null;
-    /**
-     * 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.
-     */
-    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;
-    };
-}
-/**
- * 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.
-     * @param filePath - The storage path of the file
-     * @returns The file data as a Blob or base64 string
-     */
-    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 cache management.
- */
-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;
-}
-/**
- * Default cache configuration.
- */
-declare const DEFAULT_CACHE_CONFIG: CacheConfig;
-/**
- * Configuration for the POL attachment queue.
- * Extends the official @powersync/attachments options with our features.
- */
-interface PolAttachmentQueueConfig {
-    /** Source table configuration for watching attachment IDs */
-    source: AttachmentSourceConfig;
-    /** Remote storage adapter for downloading files */
-    remoteStorage: AttachmentStorageAdapter;
-    /** Table name for storing attachment records (default: "attachments") */
-    attachmentTableName?: string;
-    /** Perform initial sync on initialization (default: true) */
-    performInitialSync?: boolean;
-    /** 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: PolAttachmentRecord, error: Error) => Promise<{
-        retry: boolean;
-    }>;
-    /**
-     * Called when sync progress changes.
-     */
-    onProgress?: (stats: AttachmentSyncStats) => void;
-    /** Upload configuration (optional - enables upload queue) */
-    upload?: {
-        handler: UploadHandler;
-        config?: Partial<UploadConfig>;
-    };
-    /**
-     * Called when an upload completes successfully.
-     * Use this to create CRUD records after file upload.
-     */
-    onUploadComplete?: (record: PolAttachmentRecord) => Promise<void>;
-    /**
-     * Called when an upload fails permanently.
-     */
-    onUploadFailed?: (record: PolAttachmentRecord, error: Error) => void;
-}
-/**
- * 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[];
-}
-/** 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:
- * - Configurable source table watching for attachment IDs
- * - Project filtering for multi-tenant scenarios
- * - 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: {
- *     table: 'EquipmentUnitMediaContent',
- *     idColumn: 'storagePath',
- *     orderByColumn: 'takenOn',
- *   },
- * });
- *
- * await queue.init();
- * ```
- */
-
-/**
- * Options for PolAttachmentQueue that extend the official AttachmentQueueOptions.
- */
-interface PolAttachmentQueueOptions extends AttachmentQueueOptions {
-    /**
-     * Platform adapter for file system and other platform operations.
-     */
-    platform: PlatformAdapter;
-    /**
-     * Remote storage adapter for upload/download operations.
-     */
-    remoteStorage: AttachmentStorageAdapter;
-    /**
-     * Source table configuration for watching attachment IDs.
-     */
-    source: AttachmentSourceConfig;
-    /**
-     * Upload handler for uploading files to remote storage.
-     */
-    uploadHandler?: UploadHandler;
-    /**
-     * Upload configuration.
-     */
-    uploadConfig?: Partial<UploadConfig>;
-    /**
-     * Called when an upload completes successfully.
-     */
-    onUploadComplete?: (record: PolAttachmentRecord) => Promise<void>;
-    /**
-     * Called when an upload fails permanently.
-     */
-    onUploadFailed?: (record: PolAttachmentRecord, error: Error) => void;
-    /**
-     * Compression configuration.
-     */
-    compression?: Partial<CompressionConfig>;
-    /**
-     * Cache configuration.
-     */
-    cache?: Partial<CacheConfig>;
-}
-/**
- * POL Attachment Queue that extends the official AbstractAttachmentQueue.
- *
- * This class adds:
- * - Configurable source table watching (not hardcoded to a single table)
- * - Project filtering for multi-tenant scenarios
- * - Durable upload queue with exponential backoff
- * - FAILED_PERMANENT state for permanent upload failures
- * - Image compression integration
- */
-declare class PolAttachmentQueue extends AbstractAttachmentQueue<PolAttachmentQueueOptions> {
-    /**
-     * Override parent's watchUploads to prevent dual upload engines.
-     * POL uses custom _startUploadProcessing() for uploads with:
-     * - Exponential backoff retry
-     * - Compression support
-     * - Custom metadata handling
-     *
-     * The parent's simple upload watcher would conflict and fail
-     * because POL records use upload_source_uri instead of local_uri.
-     */
-    watchUploads(): void;
-    /**
-     * Override parent's uploadAttachment to prevent misuse.
-     * POL uploads use upload_source_uri, not local_uri.
-     * External code should use queueUpload() instead.
-     */
-    uploadAttachment(record: {
-        id: string;
-    }): Promise<boolean>;
-    private readonly platform;
-    private readonly polLogger;
-    private readonly source;
-    private readonly uploadHandler?;
-    private readonly uploadConfig;
-    private readonly compressionConfig;
-    private readonly cacheConfig;
-    private _uploadProcessing;
-    private _uploadPaused;
-    private _uploadAbort;
-    private _activeUploads;
-    private _watchInterval;
-    private _disposed;
-    private _initialized;
-    private _progressCallbacks;
-    private _lastNotifyTime;
-    private _notifyTimer;
-    private _cachedStats;
-    private _cachedStatsTimestamp;
-    constructor(options: PolAttachmentQueueOptions);
-    /**
-     * Validate that a string is a safe SQL identifier (Warning 5).
-     * Prevents SQL injection via config values.
-     */
-    private _validateSqlIdentifier;
-    /**
-     * Watch the source table for attachment IDs and notify when they change.
-     *
-     * This implementation uses our configurable source table pattern rather
-     * than a hardcoded query, supporting project filtering for multi-tenant apps.
-     */
-    onAttachmentIdsChange(onUpdate: (ids: string[]) => void): void;
-    /**
-     * Create a new attachment record with POL-specific defaults.
-     */
-    newAttachmentRecord(record?: Partial<AttachmentRecord$1>): Promise<AttachmentRecord$1>;
-    /**
-     * Initialize the attachment queue.
-     *
-     * Extends parent init() to also:
-     * - Create the attachment table (since we don't use AttachmentTable in Schema)
-     * - Add upload-specific columns to the table
-     * - Start upload processing if handler is configured
-     */
-    init(): Promise<void>;
-    /**
-     * Create the attachment table if it doesn't exist.
-     * This creates a REAL SQLite table (not a view) that supports all SQL operations.
-     */
-    private _createTableIfNotExists;
-    /**
-     * Dispose the attachment queue, cleaning up all resources.
-     */
-    dispose(): void;
-    /**
-     * Queue a file for upload.
-     *
-     * The file is immediately copied to managed cache for durability.
-     * Upload will retry indefinitely for transient errors until marked
-     * as FAILED_PERMANENT for unrecoverable errors.
-     */
-    queueUpload(options: {
-        storagePath: string;
-        sourceUri: string;
-        filename: string;
-        mediaType: string;
-        bucketId?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<void>;
-    /**
-     * Get pending uploads that need retry.
-     */
-    getPendingUploads(): Promise<PolAttachmentRecord[]>;
-    /**
-     * Get the soonest retry time for all uploads currently in backoff.
-     * Returns null if there are no uploads waiting for retry.
-     */
-    getSoonestRetryTime(): Promise<number | null>;
-    /**
-     * Get uploads that have permanently failed.
-     */
-    getFailedPermanentUploads(): Promise<PolAttachmentRecord[]>;
-    /**
-     * Get stale uploads (failing for > staleDaysThreshold).
-     */
-    getStaleUploads(): Promise<PolAttachmentRecord[]>;
-    /**
-     * Get SYNCED uploads that have pending onComplete callbacks.
-     * Used by useQueuedUpload to recover callbacks after unmount/remount.
-     *
-     * Records are identified by having 'onCompleteCallback' flag in their upload_metadata.
-     * Once the callback is invoked, the hook should call clearUploadCallback() to remove the flag.
-     */
-    getSyncedUploadsWithPendingCallback(): Promise<PolAttachmentRecord[]>;
-    /**
-     * Clear the onCompleteCallback flag from a record's metadata after callback invocation.
-     */
-    clearUploadCallback(id: string): Promise<void>;
-    /**
-     * Retry a failed upload.
-     */
-    retryUpload(id: string): Promise<void>;
-    /**
-     * Delete an upload from the queue.
-     */
-    deleteUpload(id: string): Promise<void>;
-    /**
-     * Alias for record() for backward compatibility.
-     * Returns an attachment record by ID.
-     */
-    getRecord(id: string): Promise<PolAttachmentRecord | null>;
-    /**
-     * Alias for getFailedPermanentUploads() for backward compatibility.
-     */
-    getFailedUploads(): Promise<PolAttachmentRecord[]>;
-    /**
-     * Alias for retryUpload() for backward compatibility.
-     */
-    retryFailedUpload(id: string): Promise<void>;
-    /**
-     * Alias for deleteUpload() for backward compatibility.
-     */
-    deleteFailedUpload(id: string): Promise<void>;
-    /**
-     * Get currently active uploads.
-     */
-    get activeUploads(): UploadStatus[];
-    /**
-     * Pause upload processing.
-     */
-    pauseUploads(): void;
-    /**
-     * Resume upload processing.
-     */
-    resumeUploads(): void;
-    /**
-     * Clear all cached files and re-queue for download.
-     */
-    clearCache(): Promise<void>;
-    /**
-     * 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>;
-    /**
-     * Get the local file URI for a storage path.
-     * Checks both downloaded files (SYNCED state, local_uri) and
-     * pending uploads (QUEUED_UPLOAD state, upload_source_uri).
-     *
-     * @param storagePath - The storage path (e.g., "14/uuid.jpg")
-     * @returns Full file:// URI if available locally, null otherwise
-     */
-    getLocalUriForStoragePath(storagePath: string): Promise<string | null>;
-    /**
-     * Subscribe to real-time progress updates.
-     * Returns an unsubscribe function.
-     */
-    onProgress(callback: (stats: AttachmentSyncStats) => void): () => void;
-    /**
-     * Get current sync statistics.
-     */
-    getStats(): Promise<AttachmentSyncStats>;
-    private _startUploadProcessing;
-    private _uploadOne;
-    private _isPermanentError;
-    /**
-     * Extract HTTP status code from error message.
-     * Uses specific patterns to avoid false positives from numbers in other contexts.
-     */
-    private _extractErrorCode;
-    private _markUploadSynced;
-    private _markUploadPermanentFailure;
-    private _scheduleUploadRetry;
-    private _startPolling;
-    private _migrateUploadColumns;
-    private _copyToManagedCache;
-    private _getStatus;
-    private _notify;
-    private _sleep;
-    /**
-     * Warning 6: Enhanced timeout that supports AbortSignal for actual cancellation.
-     * When signal is provided and aborts, the promise rejects with an AbortError.
-     */
-    private _withTimeout;
-}
-/**
- * Create a PolAttachmentQueue from a simplified config.
- *
- * This is a convenience factory that converts from the user-friendly
- * PolAttachmentQueueConfig to the options required by PolAttachmentQueue.
- */
-declare function createPolAttachmentQueue(powersync: AbstractPowerSyncDatabase, platform: PlatformAdapter, config: PolAttachmentQueueConfig): PolAttachmentQueue;
-
-export { type AttachmentSourceConfig as A, type CompressionConfig as C, DEFAULT_COMPRESSION_CONFIG as D, type EvictRow as E, type IdRow as I, PolAttachmentQueue as P, type UploadConfig as U, type PolAttachmentQueueOptions as a, PolAttachmentState as b, createPolAttachmentQueue as c, type PolAttachmentRecord as d, type AttachmentStorageAdapter as e, DEFAULT_UPLOAD_CONFIG as f, type UploadHandler as g, type CacheConfig as h, DEFAULT_CACHE_CONFIG as i, type PolAttachmentQueueConfig as j, type DownloadPhase as k, type DownloadStatus as l, type UploadPhase as m, type UploadStatus as n, type AttachmentSyncStatus as o, type AttachmentSyncStats as p, type AttachmentStatsRow as q, type CacheFileRow as r, type CachedSizeRow as s, type AttachmentRecord as t };