@pol-studios/powersync 1.0.6 → 1.0.10

package/dist/{index-l3iL9Jte.d.ts → types-B212hgfA.d.ts}

@@ -1,7 +1,6 @@
 import { SupabaseClient } from '@supabase/supabase-js';
-import { C as CrudEntry, i as ClassifiedError, P as PowerSyncBackendConnector, A as AbstractPowerSyncDatabase } from './types-afHtE1U_.js';
+import { C as CrudEntry, i as ClassifiedError } from './types-CDqWh56B.js';
 import { LoggerAdapter } from './platform/index.js';
-import { F as FailedUpload } from './failed-upload-store-C0cLxxPz.js';
 
 /**
  * Conflict Types for @pol-studios/powersync
@@ -86,10 +85,13 @@ type ResolutionListener = (table: string, recordId: string, resolution: Conflict
  * 4. Connector subscribes via bus.onResolution() -> triggers re-upload
  */
 declare class ConflictBus {
+    private static MAX_PENDING;
     private conflictListeners;
     private resolutionListeners;
+    private pendingConflicts;
     /**
      * Subscribe to conflict detection events.
+     * Flushes any pending conflicts to ALL listeners (including the new one).
      * @returns Unsubscribe function
      */
     onConflict(listener: ConflictListener): () => void;
@@ -100,6 +102,7 @@ declare class ConflictBus {
     onResolution(listener: ResolutionListener): () => void;
     /**
      * Emit a conflict detection event (called by connector).
+     * If no listeners are subscribed, queues the conflict for later delivery.
      */
     emitConflict(conflict: ConflictCheckResult): void;
     /**
@@ -107,9 +110,13 @@ declare class ConflictBus {
      */
     emitResolution(table: string, recordId: string, resolution: ConflictResolution): void;
     /**
-     * Clear all listeners (for cleanup).
+     * Clear all listeners and pending conflicts (for cleanup).
      */
     destroy(): void;
+    /**
+     * Get the number of pending conflicts (useful for debugging/testing).
+     */
+    get pendingCount(): number;
 }
 
 /**
@@ -118,6 +125,37 @@ declare class ConflictBus {
  * Defines interfaces for PowerSync backend connectors.
  */
 
+/**
+ * Circuit breaker configuration for the connector.
+ * Prevents cascading failures by stopping requests when service is down.
+ */
+interface ConnectorCircuitBreakerConfig {
+    /**
+     * Enable circuit breaker pattern.
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Number of failures required to trip the circuit.
+     * @default 5
+     */
+    failureThreshold?: number;
+    /**
+     * Time window in ms for counting failures.
+     * @default 60000 (60 seconds)
+     */
+    failureWindowMs?: number;
+    /**
+     * Initial delay before transitioning from OPEN to HALF_OPEN.
+     * @default 1000 (1 second)
+     */
+    initialRecoveryDelayMs?: number;
+    /**
+     * Maximum delay for exponential backoff.
+     * @default 32000 (32 seconds)
+     */
+    maxRecoveryDelayMs?: number;
+}
 /**
  * Options for creating a SupabaseConnector
  */
@@ -168,6 +206,13 @@ interface SupabaseConnectorOptions {
      * @default DEFAULT_RETRY_CONFIG
      */
     retryConfig?: Partial<RetryConfig>;
+    /**
+     * Optional: Configuration for circuit breaker pattern.
+     * When enabled, prevents cascading failures by stopping requests when
+     * the service is experiencing high failure rates.
+     * @default { enabled: false }
+     */
+    circuitBreaker?: ConnectorCircuitBreakerConfig;
 }
 /**
  * Configuration passed to PowerSyncProvider for connector setup
@@ -279,182 +324,80 @@ interface RetryStrategyConfig {
 interface RetryConfig {
     /** Retry config for transient errors (network, server 5xx) */
     transient: RetryStrategyConfig;
-    /** Retry config for permanent errors (RLS, validation, constraints) */
+    /** Retry config for permanent errors (validation, constraints) */
     permanent: RetryStrategyConfig;
+    /** Retry config for RLS/permission errors (42501, row-level security violations) */
+    rls: RetryStrategyConfig;
 }
 /**
  * Default retry configuration
+ *
+ * Uses fast exponential backoff for transient errors (network issues):
+ * - Transient: 1s → 2s → 4s
+ *
+ * RLS/permission errors (42501, row-level security violations) use extended delays
+ * because parent data may need time to sync before child records can be inserted.
+ * - RLS: 30s → 60s → 120s → 120s → 120s (5 retries over ~7.5 minutes)
+ *
+ * Other permanent errors (validation, constraints) get NO retries
+ * because they will never succeed - fail fast and surface to user.
+ * PowerSync's native retry mechanism will re-attempt on next sync cycle.
  */
 declare const DEFAULT_RETRY_CONFIG: RetryConfig;
-
 /**
- * Supabase Connector for PowerSync
- *
- * A generic, configurable connector that handles:
- * - Authentication with Supabase JWT tokens
- * - Uploading local changes back to Supabase
- * - Schema routing for multi-schema databases
- * - Custom CRUD handling for complex operations
- * - Version-based conflict detection (when enabled)
+ * Session representation for authentication.
+ * Used by AuthProvider to communicate auth state.
  */
-
+interface Session {
+    /** Access token for API requests */
+    accessToken: string;
+    /** When the token expires (optional) */
+    expiresAt?: Date;
+    /** User information (optional) */
+    user?: {
+        id: string;
+    };
+}
 /**
- * Generic Supabase connector for PowerSync.
- *
- * This connector handles authentication and CRUD uploads to Supabase.
- * It supports configurable schema routing and custom CRUD handlers
- * for complex use cases.
+ * Authentication provider interface.
+ * Abstracts auth for the connector - works with any auth backend.
  *
- * @example Basic usage
+ * @example
  * ```typescript
- * const connector = new SupabaseConnector({
- *   supabaseClient: supabase,
- *   powerSyncUrl: 'https://your-powersync-instance.com',
- * });
- * ```
+ * // Using built-in Supabase adapter
+ * const auth = createSupabaseAuth(supabaseClient);
  *
- * @example With schema routing
- * ```typescript
- * const connector = new SupabaseConnector({
- *   supabaseClient: supabase,
- *   powerSyncUrl: 'https://your-powersync-instance.com',
- *   schemaRouter: (table) => {
- *     if (['Profile', 'Comment', 'CommentSection'].includes(table)) {
- *       return 'core';
- *     }
- *     return 'public';
+ * // Custom implementation
+ * const auth: AuthProvider = {
+ *   getSession: async () => ({ accessToken: myToken }),
+ *   refreshSession: async () => {
+ *     const newToken = await myAuthService.refresh();
+ *     return { accessToken: newToken };
  *   },
- * });
- * ```
- *
- * @example With custom CRUD handler
- * ```typescript
- * const connector = new SupabaseConnector({
- *   supabaseClient: supabase,
- *   powerSyncUrl: 'https://your-powersync-instance.com',
- *   crudHandler: {
- *     async handlePut(entry, supabase, schema) {
- *       // Custom handling for specific tables
- *       if (entry.table === 'SpecialTable') {
- *         await myCustomUpsert(entry);
- *         return true; // Handled
- *       }
- *       return false; // Use default
- *     },
+ *   onAuthStateChange: (cb) => {
+ *     return myAuthService.subscribe(cb);
  *   },
- * });
+ * };
  * ```
  */
-declare class SupabaseConnector implements PowerSyncBackendConnector {
-    private readonly supabase;
-    private readonly powerSyncUrl;
-    private readonly schemaRouter;
-    private readonly crudHandler?;
-    private readonly logger?;
-    private readonly onTransactionSuccess?;
-    private readonly onTransactionFailure?;
-    private readonly onTransactionComplete?;
-    private readonly shouldUploadFn?;
-    private readonly conflictDetection?;
-    private readonly conflictHandler?;
-    private readonly conflictBus?;
-    private versionColumnCache;
-    private activeProjectIds;
-    private resolvedConflicts;
-    private unsubscribeResolution?;
-    private retryConfig;
-    private autoRetryPaused;
-    constructor(options: SupabaseConnectorOptions);
+interface AuthProvider {
     /**
-     * Clean up resources (unsubscribe from event listeners).
-     * Call this when the connector is no longer needed.
+     * Get the current session.
+     * @returns Current session or null if not authenticated
      */
-    destroy(): void;
+    getSession(): Promise<Session | null>;
     /**
-     * Pause automatic retry of failed uploads.
-     * Use this when the user goes offline intentionally or wants manual control.
+     * Refresh the current session.
+     * @throws Error if refresh fails (e.g., refresh token expired)
+     * @returns New session with fresh access token
      */
-    pauseAutoRetry(): void;
+    refreshSession(): Promise<Session>;
     /**
-     * Resume automatic retry of failed uploads.
-     */
-    resumeAutoRetry(): void;
-    /**
-     * Manually retry all failed uploads that are ready for retry.
-     * This processes entries from the failed upload store.
-     */
-    retryFailedUploads(): Promise<void>;
-    /**
-     * Clear all failed uploads from the store.
-     * Use with caution - this discards all pending retries.
-     */
-    clearFailedUploads(): void;
-    /**
-     * Get all failed uploads from the store.
-     */
-    getFailedUploads(): FailedUpload[];
-    /**
-     * Process a single CRUD entry with exponential backoff retry.
-     *
-     * @param entry - The CRUD entry to process
-     * @throws Error if all retries exhausted (for critical failures)
-     */
-    private processWithRetry;
-    /**
-     * Set the active project IDs for scoped sync.
-     * Call this when user selects/opens projects.
-     */
-    setActiveProjectIds(projectIds: string[]): void;
-    /**
-     * Get the current active project IDs.
-     */
-    getActiveProjectIds(): string[];
-    /**
-     * Get credentials for PowerSync connection.
-     * Uses Supabase session token.
-     *
-     * Note: Token refresh is handled by Supabase's startAutoRefresh() which must be
-     * called on app initialization. getSession() returns the auto-refreshed token.
-     */
-    fetchCredentials(): Promise<PowerSyncCredentials>;
-    /**
-     * Upload local changes to Supabase.
-     * Called automatically by PowerSync when there are pending uploads.
-     *
-     * When conflict detection is enabled:
-     * 1. Checks if table has _version column (cached)
-     * 2. If yes, compares local vs server version
-     * 3. On version mismatch, queries AuditLog for field conflicts
-     * 4. If conflicts found, calls handler or publishes to conflict bus
-     * 5. Applies resolution or skips entry based on handler response
-     */
-    uploadData(database: AbstractPowerSyncDatabase): Promise<void>;
-    /**
-     * Process a transaction without conflict detection.
-     * Used when conflict detection is disabled.
-     */
-    private processTransaction;
-    /**
-     * Check if a table has a _version column (cached).
-     */
-    private checkVersionColumn;
-    /**
-     * Filter opData to only include specified fields.
-     * Used for partial sync resolution.
-     */
-    private filterFields;
-    /**
-     * Process a single CRUD operation.
-     *
-     * UUID-native tables (public schema, post-migration) use `id` as the UUID column.
-     * Core schema tables (Profile, Comment, CommentSection) still use a separate `uuid` column.
-     */
-    /**
-     * Process a single CRUD operation.
-     *
-     * All synced tables use `id` as their UUID primary key column.
+     * Subscribe to auth state changes.
+     * @param cb - Callback fired when auth state changes
+     * @returns Unsubscribe function
      */
-    private processCrudEntry;
+    onAuthStateChange(cb: (session: Session | null) => void): () => void;
 }
 
-export { type ConnectorConfig as C, DEFAULT_RETRY_CONFIG as D, type FieldConflict as F, type PowerSyncCredentials as P, type RetryStrategyConfig as R, SupabaseConnector as S, type SupabaseConnectorOptions as a, type SchemaRouter as b, type CrudHandler as c, defaultSchemaRouter as d, type RetryConfig as e, ConflictBus as f, type ConflictCheckResult as g, type ConflictResolution as h, type ConflictHandler as i, type ConflictDetectionConfig as j, type ConflictListener as k, type ResolutionListener as l };
+export { type AuthProvider as A, type ConnectorCircuitBreakerConfig as C, DEFAULT_RETRY_CONFIG as D, type FieldConflict as F, type PowerSyncCredentials as P, type RetryStrategyConfig as R, type SupabaseConnectorOptions as S, type ConnectorConfig as a, type SchemaRouter as b, type CrudHandler as c, defaultSchemaRouter as d, type RetryConfig as e, type Session as f, ConflictBus as g, type ConflictCheckResult as h, type ConflictResolution as i, type ConflictHandler as j, type ConflictDetectionConfig as k, type ConflictListener as l, type ResolutionListener as m };

package/dist/{types-afHtE1U_.d.ts → types-CDqWh56B.d.ts}

@@ -39,6 +39,8 @@ interface CrudEntry {
     opData?: Record<string, unknown>;
     /** Transaction ID for grouping operations */
     transactionId?: number;
+    /** When this mutation was created (for display purposes) */
+    createdAt?: Date;
 }
 /**
  * Download progress information during sync

package/dist/types-CyvBaAl8.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Upload Handler Types for @pol-studios/powersync
+ *
+ * Defines types for platform-specific upload handlers.
+ */
+/**
+ * Bucket configuration for multi-bucket routing.
+ */
+interface BucketConfig {
+    /** Default bucket for storage operations */
+    defaultBucket: string;
+    /** Map of path prefixes to bucket names */
+    bucketMap?: Map<string, string>;
+    /** Custom bucket resolver function */
+    resolver?: (storagePath: string) => string | undefined;
+}
+/**
+ * Options for creating a SupabaseUploadHandler.
+ */
+interface SupabaseUploadHandlerOptions {
+    /** Supabase client instance */
+    supabaseClient: any;
+    /** Bucket configuration for multi-bucket routing */
+    bucketConfig: BucketConfig;
+}
+/**
+ * Event handlers for upload progress tracking.
+ */
+interface UploadEventHandlers {
+    /** Called with progress updates during upload */
+    onProgress?: (progress: {
+        loaded: number;
+        total: number;
+    }) => void;
+    /** Called when upload completes successfully */
+    onComplete?: () => void;
+    /** Called when upload fails */
+    onError?: (error: Error) => void;
+}
+/**
+ * Configuration for native upload notifications (Android).
+ */
+interface UploadNotificationConfig {
+    /** Whether to show upload notifications */
+    enabled: boolean;
+    /** Whether to auto-clear notification on completion */
+    autoClear: boolean;
+    /** Title shown during upload progress */
+    onProgressTitle: string;
+    /** Title shown when upload completes */
+    onCompleteTitle: string;
+    /** Title shown when upload fails */
+    onErrorTitle: string;
+}
+/**
+ * Default notification configuration for Android uploads.
+ */
+declare const DEFAULT_UPLOAD_NOTIFICATION: UploadNotificationConfig;
+
+export { type BucketConfig as B, DEFAULT_UPLOAD_NOTIFICATION as D, type SupabaseUploadHandlerOptions as S, type UploadEventHandlers as U, type UploadNotificationConfig as a };

package/dist/types-D0WcHrq6.d.ts

@@ -0,0 +1,234 @@
+import { FileSystemAdapter, LoggerAdapter } from './platform/index.js';
+
+/**
+ * Unified Storage Types for @pol-studios/powersync
+ *
+ * Single storage interface for all Supabase storage operations.
+ * Consolidates the previous 6 fragmented interfaces into one:
+ * - AttachmentStorageAdapter (attachments/types.ts)
+ * - RemoteStorageAdapter (storage/types.ts - removed)
+ * - StorageAdapter (@powersync/attachments)
+ * - PowerSyncStorageAdapter (storage/types.ts - removed)
+ * - StorageUploadHandler (storage/types.ts - removed)
+ * - UploadHandler (attachments/types.ts)
+ */
+/**
+ * Unified storage interface for Supabase storage operations.
+ * Handles both upload and download for attachments.
+ *
+ * This is the ONLY storage interface consumers need to implement.
+ * It replaces all previous storage adapter interfaces.
+ *
+ * @example
+ * ```typescript
+ * const storage: SupabaseStorage = {
+ *   async download(path) {
+ *     const { data } = await supabase.storage
+ *       .from('attachments')
+ *       .createSignedUrl(path, 60);
+ *     // Download to temp file and return URI
+ *     return tempFileUri;
+ *   },
+ *
+ *   async upload(path, localUri, mediaType) {
+ *     const file = await readFile(localUri);
+ *     await supabase.storage
+ *       .from('attachments')
+ *       .upload(path, file, { contentType: mediaType });
+ *   },
+ * };
+ * ```
+ */
+interface SupabaseStorage {
+    /**
+     * Download a file and return the local file:// URI.
+     *
+     * @param path - Remote storage path
+     * @returns Local file:// URI pointing to the downloaded file
+     */
+    download(path: string): Promise<string>;
+    /**
+     * Upload a local file to remote storage.
+     *
+     * @param path - Remote storage path
+     * @param localUri - Local file:// URI to upload from
+     * @param mediaType - MIME type of the file
+     * @param signal - Optional AbortSignal for cancellation
+     */
+    upload(path: string, localUri: string, mediaType: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Delete a file from remote storage.
+     * Optional - not all implementations need deletion.
+     *
+     * @param path - Remote storage path to delete
+     */
+    delete?(path: string): Promise<void>;
+    /**
+     * Resolve which bucket a path belongs to.
+     * Optional - useful for multi-bucket configurations.
+     *
+     * @param path - Remote storage path
+     * @returns The bucket name
+     */
+    resolveBucket?(path: string): string;
+}
+/**
+ * Download result discriminated union.
+ * Native platforms return file URIs, web returns blobs.
+ */
+type DownloadResult = {
+    type: 'file';
+    uri: string;
+} | {
+    type: 'blob';
+    data: Blob;
+};
+/**
+ * Storage backend returned by createSupabaseStorage factory.
+ * This is a more flexible interface that returns discriminated unions
+ * to handle both native (file URI) and web (blob) download results.
+ *
+ * For simpler use cases, use SupabaseStorage interface directly.
+ */
+interface StorageBackend {
+    /** Download a file, returns discriminated union based on platform */
+    download(path: string): Promise<DownloadResult>;
+    /** Upload a local file to remote storage */
+    upload(path: string, localUri: string, contentType: string, options?: StorageUploadOptions): Promise<void>;
+    /** Delete a file from remote storage */
+    delete(path: string): Promise<void>;
+    /** Resolve which bucket a path belongs to */
+    resolveBucket(path: string): string;
+}
+/**
+ * Progress information for upload operations.
+ */
+interface UploadProgress {
+    /** Bytes uploaded so far */
+    loaded: number;
+    /** Total bytes to upload */
+    total: number;
+}
+/**
+ * Options for upload operations.
+ */
+interface StorageUploadOptions {
+    /** AbortSignal for cancellation support */
+    signal?: AbortSignal;
+    /** Progress callback */
+    onProgress?: (progress: UploadProgress) => void;
+}
+
+/**
+ * Options for creating a Supabase storage backend.
+ */
+interface SupabaseStorageOptions {
+    /** Supabase client instance */
+    client: SupabaseClient;
+    /** Default storage bucket */
+    defaultBucket: string;
+    /**
+     * Map of path prefixes to bucket names.
+     * Checked in iteration order (use Map to preserve order).
+     *
+     * @example
+     * ```typescript
+     * bucketMap: new Map([
+     *   ['avatars/', 'user-avatars'],
+     *   ['docs/', 'documents'],
+     * ])
+     * ```
+     */
+    bucketMap?: Map<string, string>;
+    /**
+     * Custom bucket resolver function.
+     * Takes precedence over bucketMap.
+     * Return undefined to fall through to bucketMap/defaultBucket.
+     */
+    bucketResolver?: (storagePath: string) => string | undefined;
+    /**
+     * Signed URL expiry in seconds.
+     * @default 60 (short-lived for security)
+     */
+    signedUrlExpiry?: number;
+    /**
+     * File system adapter for native file operations.
+     * Required for native platforms to enable file-based downloads.
+     */
+    fileSystem?: FileSystemAdapter;
+    /**
+     * Optional logger for diagnostic messages.
+     */
+    logger?: LoggerAdapter;
+}
+/**
+ * Transform options for Supabase image transformation.
+ * See: https://supabase.com/docs/guides/storage/serving/image-transformations
+ */
+interface SupabaseTransformOptions {
+    width?: number;
+    height?: number;
+    resize?: 'cover' | 'contain' | 'fill';
+    format?: 'origin' | 'avif' | 'webp';
+    quality?: number;
+}
+/**
+ * Minimal Supabase client interface for storage operations.
+ * Using a minimal interface to avoid version conflicts with @supabase/supabase-js.
+ */
+interface SupabaseClient {
+    storage: {
+        from(bucket: string): {
+            createSignedUrl(path: string, expiresIn: number, options?: {
+                download?: string | boolean;
+                transform?: SupabaseTransformOptions;
+            }): Promise<{
+                data: {
+                    signedUrl: string;
+                } | null;
+                error: Error | null;
+            }>;
+            upload(path: string, file: Blob | ArrayBuffer | FormData, options?: {
+                contentType?: string;
+                upsert?: boolean;
+            }): Promise<{
+                data: {
+                    path: string;
+                } | null;
+                error: Error | null;
+            }>;
+            remove(paths: string[]): Promise<{
+                data: {
+                    name: string;
+                }[] | null;
+                error: Error | null;
+            }>;
+            list(path?: string, options?: {
+                search?: string;
+                limit?: number;
+            }): Promise<{
+                data: {
+                    name: string;
+                }[] | null;
+                error: Error | null;
+            }>;
+        };
+    };
+    auth: {
+        refreshSession(): Promise<{
+            data: unknown;
+            error: Error | null;
+        }>;
+    };
+}
+/**
+ * Resolve bucket from storage path using SupabaseStorageOptions.
+ *
+ * Resolution order:
+ * 1. Custom bucketResolver (if provided and returns a value)
+ * 2. bucketMap prefix matching (if provided)
+ * 3. defaultBucket
+ */
+declare function resolveBucket(options: Pick<SupabaseStorageOptions, 'defaultBucket' | 'bucketMap' | 'bucketResolver'>, storagePath: string): string;
+
+export { type DownloadResult as D, type SupabaseStorage as S, type UploadProgress as U, type StorageBackend as a, type StorageUploadOptions as b, type SupabaseStorageOptions as c, type SupabaseClient as d, type SupabaseTransformOptions as e, resolveBucket as r };