@pol-studios/powersync 1.0.4 → 1.0.7

package/dist/provider/index.d.ts

@@ -1,12 +1,16 @@
 import { SupabaseClient } from '@supabase/supabase-js';
 import { QueryClient } from '@tanstack/react-query';
-import { A as AbstractPowerSyncDatabase, a as SyncStatus, C as CrudEntry, S as SyncMode, F as FailedTransaction, h as CompletedTransaction, b as ConnectionHealth, e as SyncMetrics, D as DownloadProgress, E as EntitySyncState, f as SyncError } from '../types-afHtE1U_.js';
+import { A as AbstractPowerSyncDatabase, a as SyncStatus, C as CrudEntry, S as SyncMode, F as FailedTransaction, h as CompletedTransaction, b as ConnectionHealth, e as SyncMetrics, D as DownloadProgress, E as EntitySyncState, f as SyncError } from '../types-CDqWh56B.js';
 import { PlatformAdapter } from '../platform/index.js';
-import { C as ConnectorConfig, S as SupabaseConnector, e as ConflictBus } from '../index-Cb-NI0Ct.js';
-import { AttachmentQueueConfig, AttachmentQueue } from '../attachments/index.js';
+import { b as ConnectorConfig, S as SupabaseConnector, g as ConflictBus } from '../supabase-connector-qLm-WHkM.js';
+import { j as PolAttachmentQueueConfig, P as PolAttachmentQueue } from '../pol-attachment-queue-C7YNXXhK.js';
 import * as react from 'react';
-import react__default from 'react';
-import { c as SyncControlActions } from '../types-Cd7RhNqf.js';
+import react__default, { ReactNode } from 'react';
+import { Schema } from '@powersync/react-native';
+import { R as RemoteStorageAdapter, A as AttachmentUploadHandler } from '../types-Bgvx7-E8.js';
+import { h as BackgroundSyncSystem, c as SyncControlActions } from '../background-sync-ChCXW-EV.js';
+import '@powersync/attachments';
+import '@powersync/common';
 
 /**
  * Provider Types for @pol-studios/powersync
@@ -70,8 +74,16 @@ interface PowerSyncConfig<TSchema = unknown> {
     connector?: ConnectorConfig;
     /**
      * Optional: Attachment queue configuration for offline file caching.
+     *
+     * @example
+     * ```typescript
+     * attachments: {
+     *   source: { table: 'photos', idColumn: 'storage_path' },
+     *   remoteStorage: supabaseStorageAdapter,
+     * }
+     * ```
      */
-    attachments?: AttachmentQueueConfig;
+    attachments?: PolAttachmentQueueConfig;
     /**
      * Optional: Sync behavior configuration.
      */
@@ -123,7 +135,7 @@ interface PowerSyncContextValue<TSchema = unknown> {
      * The attachment queue instance.
      * Will be null if attachments are not configured or not initialized.
      */
-    attachmentQueue: AttachmentQueue | null;
+    attachmentQueue: PolAttachmentQueue | null;
     /**
      * Whether the PowerSync database is ready for use.
      */
@@ -132,6 +144,17 @@ interface PowerSyncContextValue<TSchema = unknown> {
      * Whether the provider is currently initializing.
      */
     isInitializing: boolean;
+    /**
+     * Whether the attachment queue is ready for use.
+     * This is separate from isReady because the attachment queue initializes
+     * asynchronously after the database is ready.
+     *
+     * States:
+     * - `false`: Attachment queue is still initializing
+     * - `true` with `attachmentQueue !== null`: Ready and available
+     * - `true` with `attachmentQueue === null`: Either attachments not configured, OR initialization failed
+     */
+    attachmentQueueReady: boolean;
     /**
      * Error that occurred during initialization, if any.
      */
@@ -191,7 +214,7 @@ interface SyncStatusContextValue {
     /**
      * Error that occurred during connection, if any.
      */
-    connectionError?: Error | null;
+    connectionError: Error | null;
     /**
      * Failed transactions that need attention.
      */
@@ -242,6 +265,145 @@ interface SyncStatusContextValue {
      * @throws Error if upload is in progress
      */
     discardAllPendingMutations: () => Promise<void>;
+    /**
+     * Pause automatic retry of failed uploads.
+     * Useful when user is actively resolving conflicts.
+     */
+    pauseAutoRetry: () => void;
+    /**
+     * Resume automatic retry of failed uploads.
+     */
+    resumeAutoRetry: () => void;
+}
+/**
+ * Connection state - changes rarely (on connect/disconnect).
+ * Use this for components that only need to display connection status.
+ */
+interface ConnectionStatusContextValue {
+    /** Whether connected to the PowerSync service */
+    connected: boolean;
+    /** Whether currently attempting to connect */
+    connecting: boolean;
+    /** Whether initial sync has completed */
+    hasSynced: boolean;
+    /** Timestamp of last successful sync */
+    lastSyncedAt: Date | null;
+    /** Error that occurred during connection, if any */
+    connectionError: Error | null;
+}
+/**
+ * Sync activity - changes during active sync.
+ * Use this for components that display sync progress.
+ */
+interface SyncActivityContextValue {
+    /** Whether data is currently being uploaded to the server */
+    uploading: boolean;
+    /** Whether data is currently being downloaded from the server */
+    downloading: boolean;
+    /** Download progress details */
+    downloadProgress: DownloadProgress | null;
+}
+/**
+ * Pending mutations - changes on local writes.
+ * Use this for components that display pending upload count or list.
+ */
+interface PendingMutationsContextValue {
+    /** Pending mutations waiting to be uploaded */
+    pendingMutations: CrudEntry[];
+    /** Number of pending mutations */
+    pendingCount: number;
+    /** Discard a specific pending mutation by its client ID */
+    discardPendingMutation: (clientId: number) => Promise<void>;
+    /** Discard all pending mutations */
+    discardAllPendingMutations: () => Promise<void>;
+    /**
+     * Add a pending mutation to the list.
+     * Called by mutation hooks (useDbInsert, useDbUpdate, useDbDelete, useDbUpsert)
+     * after a successful write. Includes createdAt timestamp for display.
+     */
+    addPendingMutation: (entry: CrudEntry) => void;
+    /**
+     * Remove a pending mutation by its entity ID.
+     * Called when a transaction completes sync.
+     */
+    removePendingMutation: (id: string) => void;
+}
+/**
+ * Failed transactions - changes on failures.
+ * Use this for components that display sync errors.
+ */
+interface FailedTransactionsContextValue {
+    /** Failed transactions that need attention */
+    failedTransactions: FailedTransaction[];
+    /** Whether there are any upload errors */
+    hasUploadErrors: boolean;
+    /** Count of permanent errors that need user action */
+    permanentErrorCount: number;
+    /** Clear a specific failure by its ID */
+    clearFailure: (failureId: string) => void;
+    /** Clear all failures */
+    clearAllFailures: () => void;
+    /** Pause automatic retry of failed uploads */
+    pauseAutoRetry: () => void;
+    /** Resume automatic retry of failed uploads */
+    resumeAutoRetry: () => void;
+    /**
+     * Retry a specific failed transaction.
+     *
+     * This removes the failure from tracking and triggers a sync.
+     * The actual CRUD entries remain in PowerSync's queue - this just
+     * clears our error tracking so the sync can retry them.
+     *
+     * If the sync fails to start, the failure is re-recorded.
+     */
+    retryFailure: (failureId: string) => Promise<void>;
+}
+/**
+ * Completed transactions - changes on successful syncs.
+ * Use this for components that display sync history.
+ */
+interface CompletedTransactionsContextValue {
+    /** Recently completed transactions */
+    completedTransactions: CompletedTransaction[];
+    /** Clear the completed transaction history */
+    clearCompletedHistory: () => void;
+    /** Clear a specific completed transaction by ID */
+    clearCompletedItem: (completedId: string) => void;
+    /**
+     * Completed transactions that occurred AFTER the last notification display.
+     * Use this for toast/banner notifications to avoid showing stale historical counts.
+     */
+    newCompletedTransactions: CompletedTransaction[];
+    /**
+     * Mark notifications as seen (updates the lastNotificationTime).
+     * Call this when a sync notification is displayed or auto-dismissed.
+     */
+    markNotificationsAsSeen: () => void;
+}
+/**
+ * Sync mode control - changes rarely (user action).
+ * Use this for components that display/control sync mode.
+ */
+interface SyncModeContextValue {
+    /** Current sync mode */
+    syncMode: SyncMode;
+    /** Whether sync is currently paused (offline mode) */
+    isPaused: boolean;
+    /**
+     * Whether offline mode was automatically set due to network loss.
+     * When true, sync will auto-resume when network returns.
+     * When false (user manually chose offline), sync won't auto-resume.
+     */
+    isAutoOffline: boolean;
+    /**
+     * Whether the network is currently reachable.
+     * This is used as a gate to block uploads even when syncMode is 'push-pull'.
+     */
+    networkReachable: boolean;
+    /** Set the sync mode (manual - won't auto-resume) */
+    setSyncMode: (mode: SyncMode) => Promise<void>;
+    /** Set the force next upload flag */
+    setForceNextUpload: (force: boolean) => void;
 }
 /**
  * Value provided by ConnectionHealthContext.
@@ -335,6 +497,36 @@ declare const PowerSyncContext: react.Context<PowerSyncContextValue<unknown>>;
  * ```
  */
 declare const SyncStatusContext: react.Context<SyncStatusContextValue>;
+/**
+ * Context for connection status only.
+ * Subscribe to this instead of SyncStatusContext when you only need connection state.
+ */
+declare const ConnectionStatusContext: react.Context<ConnectionStatusContextValue>;
+/**
+ * Context for sync activity (uploading/downloading).
+ * Subscribe to this instead of SyncStatusContext when you only need sync progress.
+ */
+declare const SyncActivityContext: react.Context<SyncActivityContextValue>;
+/**
+ * Context for pending mutations.
+ * Subscribe to this instead of SyncStatusContext when you only need pending upload info.
+ */
+declare const PendingMutationsContext: react.Context<PendingMutationsContextValue>;
+/**
+ * Context for failed transactions.
+ * Subscribe to this instead of SyncStatusContext when you only need error info.
+ */
+declare const FailedTransactionsContext: react.Context<FailedTransactionsContextValue>;
+/**
+ * Context for completed transactions.
+ * Subscribe to this instead of SyncStatusContext when you only need sync history.
+ */
+declare const CompletedTransactionsContext: react.Context<CompletedTransactionsContextValue>;
+/**
+ * Context for sync mode control.
+ * Subscribe to this instead of SyncStatusContext when you only need sync mode.
+ */
+declare const SyncModeContext: react.Context<SyncModeContextValue>;
 /**
  * Context for connection health monitoring.
  *
@@ -386,7 +578,7 @@ declare const SyncMetricsContext: react.Context<SyncMetricsContextValue>;
  * }
  * ```
  */
-declare const AttachmentQueueContext: react.Context<AttachmentQueue>;
+declare const AttachmentQueueContext: react.Context<PolAttachmentQueue>;
 
 /**
  * PowerSyncProvider Component for @pol-studios/powersync
@@ -431,6 +623,313 @@ declare const AttachmentQueueContext: react.Context<AttachmentQueue>;
  */
 declare function PowerSyncProvider<TSchema = unknown>({ config, children, onReady, onError, onSyncStatusChange, }: PowerSyncProviderProps<TSchema>): react__default.ReactElement;
 
+/**
+ * Configuration for @pol-studios/db DataLayerProvider integration.
+ * This allows OfflineDataProvider to wrap and configure the DataLayerProvider.
+ */
+interface DataLayerConfig {
+    /**
+     * Entity schemas that define tables and relationships.
+     * This is passed directly to DataLayerProvider.
+     */
+    schema: Record<string, unknown>;
+}
+/**
+ * Data layer integration configuration.
+ */
+interface DataLayerIntegration {
+    /** DataLayer configuration */
+    config: DataLayerConfig;
+    /** Skip rendering DataLayerProvider (default: false) */
+    skip?: boolean;
+}
+/**
+ * Callbacks for background sync lifecycle events.
+ */
+interface BackgroundSyncCallbacks {
+    /** Called when background sync starts */
+    onSyncStart?: () => void;
+    /** Called when background sync completes successfully */
+    onSyncComplete?: () => void;
+    /** Called when background sync fails */
+    onSyncError?: (error: Error) => void;
+}
+/**
+ * Background sync configuration.
+ */
+interface BackgroundSyncConfig {
+    /** Enable background sync */
+    enabled: boolean;
+    /** Minimum interval between background syncs in minutes (default: 15) */
+    minimumInterval?: number;
+    /** Callbacks for sync lifecycle events */
+    callbacks?: BackgroundSyncCallbacks;
+}
+/**
+ * Status reported by background sync.
+ * Compatible with the status callback in BackgroundSyncSystem.
+ */
+interface BackgroundSyncStatus {
+    /** Last successful sync timestamp */
+    lastSyncedAt?: Date | null;
+    /** Whether currently downloading */
+    downloading: boolean;
+    /** Whether currently uploading */
+    uploading: boolean;
+}
+/**
+ * Snapshot of PowerSync sync status for passing to DataLayerProvider.
+ */
+interface PowerSyncSyncStatusSnapshot {
+    /** Whether initial sync has completed */
+    hasSynced: boolean;
+    /** Whether connected to the PowerSync service */
+    connected: boolean;
+    /** Whether currently attempting to connect */
+    connecting: boolean;
+    /** Whether the device is online (from platform adapter) */
+    isOnline: boolean;
+}
+/**
+ * Attachment configuration for OfflineDataProvider
+ */
+interface OfflineDataAttachmentConfig {
+    /** Storage bucket name */
+    bucket: string;
+    /** Source table for attachments */
+    sourceTable: string;
+    /** Column containing the storage path/ID */
+    idColumn: string;
+    /** Optional: Column to order downloads by */
+    orderByColumn?: string;
+    /** Optional: Filter configuration */
+    projectFilter?: {
+        foreignKey: string;
+        intermediaryTable: string;
+        projectForeignKey: string;
+    };
+}
+/**
+ * Configuration for OfflineDataProvider
+ */
+interface OfflineDataProviderConfig {
+    /** PowerSync schema definition */
+    schema: Schema;
+    /** Supabase client instance */
+    supabaseClient: SupabaseClient;
+    /** React Query client */
+    queryClient: QueryClient;
+    /** PowerSync service URL (if missing, runs in online-only mode) */
+    powerSyncUrl?: string;
+    /** Database filename (default: 'powersync.db') */
+    dbFilename?: string;
+    /** Attachment configuration */
+    attachments?: OfflineDataAttachmentConfig;
+    /** Platform adapter (created automatically if not provided) */
+    platform?: PlatformAdapter;
+    /** Custom connector configuration for CRUD handling */
+    connector?: {
+        /** Schema router function for table-specific schema lookups */
+        schemaRouter?: (table: string) => unknown;
+        /** Enable conflict detection */
+        conflictDetection?: {
+            enabled: boolean;
+        };
+    };
+    /** Sync behavior configuration */
+    sync?: {
+        /** Automatically connect when the provider mounts and there's an authenticated session */
+        autoConnect?: boolean;
+        /** Enable health monitoring */
+        enableHealthMonitoring?: boolean;
+        /** Enable metrics collection */
+        enableMetrics?: boolean;
+    };
+}
+/**
+ * Props for OfflineDataProvider
+ */
+interface OfflineDataProviderProps {
+    /** Provider configuration */
+    config: OfflineDataProviderConfig;
+    children: ReactNode;
+    /**
+     * DataLayer configuration for @pol-studios/db integration.
+     * When provided, OfflineDataProvider wraps children with DataLayerProvider
+     * and automatically bridges PowerSync context to it.
+     */
+    dataLayer?: DataLayerIntegration;
+    /**
+     * Background sync configuration.
+     * When enabled, sets up background sync system for iOS/Android.
+     */
+    backgroundSync?: BackgroundSyncConfig;
+    /** Skip rendering ConflictProvider (default: false) */
+    skipConflictProvider?: boolean;
+    /** Skip rendering StorageQueueProvider (default: false) */
+    skipStorageQueueProvider?: boolean;
+    /** Custom storage adapter (overrides built-in Supabase adapter) */
+    storageAdapter?: RemoteStorageAdapter;
+    /** Custom upload handler */
+    uploadHandler?: AttachmentUploadHandler;
+    /** Custom error UI for initialization errors */
+    renderInitError?: (error: Error, retry: () => void) => ReactNode;
+    /**
+     * Custom error UI (alias for renderInitError for backward compatibility)
+     * @deprecated Use renderInitError instead
+     */
+    renderError?: (error: Error, retry: () => void) => ReactNode;
+    onReady?: () => void;
+    onError?: (error: Error) => void;
+    onSyncStatusChange?: (status: PowerSyncSyncStatusSnapshot) => void;
+    /**
+     * Called when the background sync system is ready.
+     * Use this to set up app-level background sync via defineBackgroundSyncTask.
+     */
+    onBackgroundSyncSystemReady?: (system: BackgroundSyncSystem) => void;
+}
+/**
+ * Props for the internal ProviderBridge component.
+ */
+interface ProviderBridgeProps {
+    children: ReactNode;
+    /** Skip ConflictProvider */
+    skipConflictProvider?: boolean;
+    /** Skip StorageQueueProvider */
+    skipStorageQueueProvider?: boolean;
+    /** Background sync configuration */
+    backgroundSync?: BackgroundSyncConfig;
+    /** Callback for background sync system setup */
+    onBackgroundSyncSystemReady?: (system: BackgroundSyncSystem | null) => void;
+    /** Called once when db becomes ready, with the db instance and initial sync status */
+    onDbReady: (db: AbstractPowerSyncDatabase | null, syncStatus: PowerSyncSyncStatusSnapshot) => void;
+    /** Called whenever sync status changes after initial readiness */
+    onSyncStatusChange: (syncStatus: PowerSyncSyncStatusSnapshot) => void;
+    /** Called with the addPendingMutation function once available */
+    onAddPendingMutationReady: (add: (entry: CrudEntry) => void) => void;
+    /** Called with the removePendingMutation function once available */
+    onRemovePendingMutationReady: (remove: (id: string) => void) => void;
+}
+
+/**
+ * OfflineDataProvider Component for @pol-studios/powersync
+ *
+ * Batteries-included offline data provider that combines:
+ * - PowerSyncProvider for offline-first data sync
+ * - DataLayerProvider integration from @pol-studios/db
+ * - ConflictProvider for conflict resolution UI
+ * - StorageQueueProvider for attachment queue access
+ * - Background sync system setup
+ * - Error recovery UI with retry capability
+ * - Online-only mode fallback (no PowerSync URL)
+ *
+ * This is the recommended entry point for apps using offline-first data.
+ *
+ * @example
+ * ```tsx
+ * <OfflineDataProvider
+ *   config={{
+ *     schema: AppSchema,
+ *     supabaseClient: supabase,
+ *     queryClient: queryClient,
+ *     powerSyncUrl: env.powerSyncUrl,
+ *     attachments: {
+ *       bucket: 'my-bucket',
+ *       sourceTable: 'MediaContent',
+ *       idColumn: 'storagePath',
+ *     },
+ *   }}
+ *   dataLayer={{ config: dataLayerConfig }}
+ *   renderInitError={(error, retry) => <MyErrorUI error={error} onRetry={retry} />}
+ * >
+ *   <App />
+ * </OfflineDataProvider>
+ * ```
+ */
+
+/**
+ * Batteries-included offline data provider.
+ *
+ * Combines PowerSyncProvider with error boundary, DataLayerProvider integration,
+ * and sensible defaults for a complete offline-first data solution.
+ *
+ * Key features:
+ * - Automatic PowerSync setup and initialization
+ * - Integration with @pol-studios/db DataLayerProvider
+ * - ConflictProvider and StorageQueueProvider wiring
+ * - Background sync system support
+ * - Error recovery UI with retry capability
+ * - Online-only mode fallback when no PowerSync URL is provided
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <OfflineDataProvider
+ *   config={{
+ *     schema: AppSchema,
+ *     supabaseClient: supabase,
+ *     queryClient: queryClient,
+ *     powerSyncUrl: process.env.EXPO_PUBLIC_POWERSYNC_URL,
+ *   }}
+ * >
+ *   <App />
+ * </OfflineDataProvider>
+ *
+ * // With DataLayer integration
+ * <OfflineDataProvider
+ *   config={{ ... }}
+ *   dataLayer={{ config: dataLayerConfig }}
+ * >
+ *   <App />
+ * </OfflineDataProvider>
+ *
+ * // With custom error UI
+ * <OfflineDataProvider
+ *   config={{ ... }}
+ *   renderInitError={(error, retry) => <MyErrorUI error={error} onRetry={retry} />}
+ * >
+ *   <App />
+ * </OfflineDataProvider>
+ * ```
+ */
+declare function OfflineDataProvider({ config, children, dataLayer, backgroundSync, skipConflictProvider, skipStorageQueueProvider, storageAdapter: customStorageAdapter, uploadHandler: customUploadHandler, renderInitError, renderError, onReady, onError, onSyncStatusChange, onBackgroundSyncSystemReady: onBackgroundSyncSystemReadyProp, }: OfflineDataProviderProps): react__default.ReactElement;
+
+/**
+ * ProviderBridge Component for @pol-studios/powersync
+ *
+ * Internal bridge component that connects PowerSync context to external providers:
+ * - DataLayerProvider from @pol-studios/db
+ * - ConflictProvider from @pol-studios/db
+ * - StorageQueueProvider from @pol-studios/db
+ *
+ * This component is used internally by OfflineDataProvider and should not be
+ * exported directly. It handles the complex wiring between packages.
+ */
+
+/**
+ * ProviderBridge connects the PowerSync package context to external providers
+ * like ConflictProvider and StorageQueueProvider from @pol-studios/db.
+ *
+ * This component:
+ * 1. Signals the parent when the db is ready (onDbReady)
+ * 2. Reports sync status changes (onSyncStatusChange)
+ * 3. Exposes pending mutation functions to parent (for DataLayerProvider)
+ * 4. Sets up background sync system when enabled
+ * 5. Wraps children with ConflictProvider and StorageQueueProvider
+ * 6. Exposes PowerSync db via native PowerSyncContext for SDK hooks
+ *
+ * IMPORTANT: DataLayerProvider is rendered OUTSIDE this component (in OfflineDataProvider)
+ * so it always exists in the React tree even before PowerSync is ready.
+ * This prevents "useDataLayer must be used within a DataLayerProvider" errors
+ * when routes mount before the db is initialized.
+ *
+ * CRITICAL: The conflictBus is created internally by PowerSyncProvider and
+ * passed to the connector. We MUST use the same bus instance from context
+ * for ConflictProvider, otherwise conflicts detected by the connector won't
+ * reach the UI components subscribed via ConflictProvider.
+ */
+declare function ProviderBridge({ children, skipConflictProvider, skipStorageQueueProvider, backgroundSync, onBackgroundSyncSystemReady, onDbReady, onSyncStatusChange, onAddPendingMutationReady, onRemovePendingMutationReady, }: ProviderBridgeProps): react__default.ReactElement | null;
+
 /**
  * Hook to access the PowerSync database and related services.
  *
@@ -452,7 +951,17 @@ declare function PowerSyncProvider<TSchema = unknown>({ config, children, onRead
  */
 declare function usePowerSync<TSchema = unknown>(): PowerSyncContextValue<TSchema>;
 /**
- * Hook to access the current sync status.
+ * @deprecated This hook causes re-renders on any status change.
+ * Use focused hooks instead:
+ *
+ * | Old (useSyncStatus)            | New hook                    |
+ * |--------------------------------|-----------------------------|
+ * | connected, hasSynced           | useConnectionStatus()       |
+ * | uploading, downloading         | useSyncActivityContext()    |
+ * | pendingCount, pendingMutations | usePendingMutationsContext()|
+ * | failedTransactions             | useFailedTransactions()     |
+ * | syncMode, setSyncMode          | useSyncMode()               |
+ * | triggerSync, pause, resume     | useSyncControl()            |
  *
  * @returns Sync status with connection state, pending uploads, and progress
  * @throws Error if used outside of PowerSyncProvider
@@ -476,6 +985,129 @@ declare function usePowerSync<TSchema = unknown>(): PowerSyncContextValue<TSchem
  * ```
  */
 declare function useSyncStatus(): SyncStatusContextValue;
+/**
+ * Hook to access connection status only.
+ * Use this instead of useSyncStatus when you only need connection state.
+ *
+ * @returns Connection status with connected, connecting, hasSynced states
+ * @throws Error if used outside of PowerSyncProvider
+ *
+ * @example
+ * ```typescript
+ * function ConnectionBadge() {
+ *   const { connected, connecting } = useConnectionStatus();
+ *
+ *   if (connecting) return <Badge>Connecting...</Badge>;
+ *   return <Badge color={connected ? 'green' : 'red'}>{connected ? 'Online' : 'Offline'}</Badge>;
+ * }
+ * ```
+ */
+declare function useConnectionStatus(): ConnectionStatusContextValue;
+/**
+ * Hook to access sync activity (uploading/downloading).
+ * Use this instead of useSyncStatus when you only need sync progress.
+ *
+ * @returns Sync activity with uploading, downloading, and downloadProgress
+ * @throws Error if used outside of PowerSyncProvider
+ *
+ * @example
+ * ```typescript
+ * function SyncProgressBar() {
+ *   const { downloading, downloadProgress } = useSyncActivityContext();
+ *
+ *   if (!downloading) return null;
+ *   return <ProgressBar value={downloadProgress?.percentage ?? 0} />;
+ * }
+ * ```
+ */
+declare function useSyncActivityContext(): SyncActivityContextValue;
+/**
+ * Hook to access pending mutations.
+ * Use this instead of useSyncStatus when you only need pending upload info.
+ *
+ * @returns Pending mutations with count and discard functions
+ * @throws Error if used outside of PowerSyncProvider
+ *
+ * @example
+ * ```typescript
+ * function PendingChangesIndicator() {
+ *   const { pendingCount } = usePendingMutationsContext();
+ *
+ *   if (pendingCount === 0) return null;
+ *   return <Badge>{pendingCount} pending</Badge>;
+ * }
+ * ```
+ */
+declare function usePendingMutationsContext(): PendingMutationsContextValue;
+/**
+ * Hook to access failed transactions.
+ * Use this instead of useSyncStatus when you only need error info.
+ *
+ * @returns Failed transactions with error counts and clear/retry functions
+ * @throws Error if used outside of PowerSyncProvider
+ *
+ * @example
+ * ```typescript
+ * function SyncErrorBanner() {
+ *   const { hasUploadErrors, permanentErrorCount, retryFailure, failedTransactions } = useFailedTransactionsContext();
+ *
+ *   if (!hasUploadErrors) return null;
+ *   return (
+ *     <Banner onRetry={() => failedTransactions.forEach(f => retryFailure(f.id))}>
+ *       {permanentErrorCount} changes failed to sync
+ *     </Banner>
+ *   );
+ * }
+ * ```
+ */
+declare function useFailedTransactionsContext(): FailedTransactionsContextValue;
+/**
+ * Hook to access completed transactions history.
+ * Use this instead of useSyncStatus when you only need sync history.
+ *
+ * @returns Completed transactions with clear function
+ * @throws Error if used outside of PowerSyncProvider
+ *
+ * @example
+ * ```typescript
+ * function RecentSyncs() {
+ *   const { completedTransactions, clearCompletedHistory } = useCompletedTransactionsContext();
+ *
+ *   return (
+ *     <View>
+ *       {completedTransactions.map(t => (
+ *         <Text key={t.id}>Synced {t.affectedEntityIds.length} items</Text>
+ *       ))}
+ *       <Button onPress={clearCompletedHistory}>Clear</Button>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+declare function useCompletedTransactionsContext(): CompletedTransactionsContextValue;
+/**
+ * Hook to access sync mode control.
+ * Use this instead of useSyncStatus when you only need sync mode.
+ *
+ * @returns Sync mode with isPaused state and control functions
+ * @throws Error if used outside of PowerSyncProvider
+ *
+ * @example
+ * ```typescript
+ * function SyncModeToggle() {
+ *   const { syncMode, isPaused, setSyncMode } = useSyncModeContext();
+ *
+ *   return (
+ *     <Toggle
+ *       value={!isPaused}
+ *       onValueChange={(on) => setSyncMode(on ? 'push-pull' : 'offline')}
+ *       label={isPaused ? 'Offline' : syncMode}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function useSyncModeContext(): SyncModeContextValue;
 /**
  * Hook to control sync operations.
  *
@@ -526,6 +1158,7 @@ declare function useSyncMode(): {
     setMode: (mode: SyncMode) => Promise<void>;
     canUpload: boolean;
     canDownload: boolean;
+    networkReachable: boolean;
 };
 /**
  * Hook to access connection health status.
@@ -610,7 +1243,36 @@ declare function useSyncMetrics(): SyncMetrics;
  * }
  * ```
  */
-declare function useAttachmentQueue(): AttachmentQueue | null;
+declare function useAttachmentQueue(): PolAttachmentQueue | null;
+/**
+ * Hook to check if the attachment queue has finished initializing.
+ *
+ * This is useful when you need to wait for the attachment queue to be ready
+ * before performing upload operations. The attachment queue initializes
+ * asynchronously after the database is ready, so there's a brief period
+ * where `isReady` is true but `attachmentQueueReady` is false.
+ *
+ * @returns Whether the attachment queue is ready (true if initialized or if attachments not configured)
+ *
+ * @example
+ * ```typescript
+ * function UploadButton() {
+ *   const attachmentQueue = useAttachmentQueue();
+ *   const attachmentQueueReady = useAttachmentQueueReady();
+ *
+ *   if (!attachmentQueueReady) {
+ *     return <Button disabled>Initializing...</Button>;
+ *   }
+ *
+ *   if (!attachmentQueue) {
+ *     return <Text>Uploads not configured</Text>;
+ *   }
+ *
+ *   return <Button onPress={handleUpload}>Upload</Button>;
+ * }
+ * ```
+ */
+declare function useAttachmentQueueReady(): boolean;
 /**
  * Hook to get the PowerSync database instance.
  * Throws if not ready.
@@ -835,20 +1497,29 @@ interface SyncActivityResult {
     failed: FailedTransaction[];
     /** Recently completed transactions */
     completed: CompletedTransaction[];
+    /** New completed transactions since last notification display (for toasts/banners) */
+    newCompleted: CompletedTransaction[];
     /** Counts summary */
     counts: {
         pending: number;
         failed: number;
         completed: number;
+        newCompleted: number;
     };
     /** Whether there is any sync activity to show (pending or failed) */
     hasActivity: boolean;
     /** Retry all failed transactions */
     retryAll: () => Promise<void>;
+    /** Retry a specific failed transaction */
+    retryFailure: (failureId: string) => Promise<void>;
     /** Dismiss a specific failure */
     dismissFailure: (failureId: string) => void;
     /** Clear all completed transactions from the list */
     clearCompleted: () => void;
+    /** Clear a specific completed transaction from the list */
+    clearCompletedItem: (completedId: string) => void;
+    /** Mark notifications as seen (for auto-dismiss functionality) */
+    markNotificationsAsSeen: () => void;
 }
 /**
  * Hook to get comprehensive sync activity including pending, failed, and completed transactions.
@@ -874,5 +1545,15 @@ interface SyncActivityResult {
  * ```
  */
 declare function useSyncActivity(): SyncActivityResult;
+/**
+ * Get failed transactions state and retry/dismiss functions.
+ * Alias for useFailedTransactionsContext.
+ */
+declare const useFailedTransactions: typeof useFailedTransactionsContext;
+/**
+ * Get completed transactions state and clear function.
+ * Alias for useCompletedTransactionsContext.
+ */
+declare const useCompletedTransactions: typeof useCompletedTransactionsContext;
 
-export { AttachmentQueueContext, ConnectionHealthContext, type ConnectionHealthContextValue, DEFAULT_CONNECTION_HEALTH, DEFAULT_SYNC_CONFIG, DEFAULT_SYNC_METRICS, DEFAULT_SYNC_STATUS, type EntitySyncStatusResult, type PowerSyncConfig, PowerSyncContext, type PowerSyncContextValue, PowerSyncProvider, type PowerSyncProviderProps, type SyncActivityResult, type SyncConfig, SyncMetricsContext, type SyncMetricsContextValue, SyncStatusContext, type SyncStatusContextValue, type UploadStatusResult, useAttachmentQueue, useConnectionHealth, useDatabase, useDownloadProgress, useEntitySyncStatus, useIsSyncing, useOnlineStatus, usePendingMutations, usePlatform, usePowerSync, useSyncActivity, useSyncControl, useSyncMetrics, useSyncMode, useSyncStatus, useUploadStatus };
+export { AttachmentQueueContext, type BackgroundSyncCallbacks, type BackgroundSyncConfig, type BackgroundSyncStatus, CompletedTransactionsContext, type CompletedTransactionsContextValue, ConnectionHealthContext, type ConnectionHealthContextValue, ConnectionStatusContext, type ConnectionStatusContextValue, DEFAULT_CONNECTION_HEALTH, DEFAULT_SYNC_CONFIG, DEFAULT_SYNC_METRICS, DEFAULT_SYNC_STATUS, type DataLayerConfig, type DataLayerIntegration, type EntitySyncStatusResult, FailedTransactionsContext, type FailedTransactionsContextValue, type OfflineDataAttachmentConfig, OfflineDataProvider, type OfflineDataProviderConfig, type OfflineDataProviderProps, PendingMutationsContext, type PendingMutationsContextValue, type PowerSyncConfig, PowerSyncContext, type PowerSyncContextValue, PowerSyncProvider, type PowerSyncProviderProps, type PowerSyncSyncStatusSnapshot, ProviderBridge, type ProviderBridgeProps, SyncActivityContext, type SyncActivityContextValue, type SyncActivityResult, type SyncConfig, SyncMetricsContext, type SyncMetricsContextValue, SyncModeContext, type SyncModeContextValue, SyncStatusContext, type SyncStatusContextValue, type UploadStatusResult, useAttachmentQueue, useAttachmentQueueReady, useCompletedTransactions, useCompletedTransactionsContext, useConnectionHealth, useConnectionStatus, useDatabase, useDownloadProgress, useEntitySyncStatus, useFailedTransactions, useFailedTransactionsContext, useIsSyncing, useOnlineStatus, usePendingMutations, usePendingMutationsContext, usePlatform, usePowerSync, useSyncActivity, useSyncActivityContext, useSyncControl, useSyncMetrics, useSyncMode, useSyncModeContext, useSyncStatus, useUploadStatus };