@pol-studios/powersync 1.0.6 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/dist/CacheSettingsManager-1exbOC6S.d.ts +261 -0
  2. package/dist/attachments/index.d.ts +65 -355
  3. package/dist/attachments/index.js +24 -6
  4. package/dist/{types-Cd7RhNqf.d.ts → background-sync-ChCXW-EV.d.ts} +53 -2
  5. package/dist/chunk-4C3RY5SU.js +204 -0
  6. package/dist/chunk-4C3RY5SU.js.map +1 -0
  7. package/dist/{chunk-3AYXHQ4W.js → chunk-53WH2JJV.js} +111 -47
  8. package/dist/chunk-53WH2JJV.js.map +1 -0
  9. package/dist/chunk-A4IBBWGO.js +377 -0
  10. package/dist/chunk-A4IBBWGO.js.map +1 -0
  11. package/dist/chunk-BREGB4WL.js +1768 -0
  12. package/dist/chunk-BREGB4WL.js.map +1 -0
  13. package/dist/{chunk-EJ23MXPQ.js → chunk-CGL33PL4.js} +3 -1
  14. package/dist/chunk-CGL33PL4.js.map +1 -0
  15. package/dist/chunk-DGUM43GV.js +11 -0
  16. package/dist/chunk-DHYUBVP7.js +131 -0
  17. package/dist/chunk-DHYUBVP7.js.map +1 -0
  18. package/dist/chunk-FV2HXEIY.js +124 -0
  19. package/dist/chunk-FV2HXEIY.js.map +1 -0
  20. package/dist/chunk-GKF7TOMT.js +1 -0
  21. package/dist/{chunk-R4YFWQ3Q.js → chunk-H772V6XQ.js} +304 -51
  22. package/dist/chunk-H772V6XQ.js.map +1 -0
  23. package/dist/{chunk-62J2DPKX.js → chunk-HFOFLW5F.js} +396 -412
  24. package/dist/chunk-HFOFLW5F.js.map +1 -0
  25. package/dist/chunk-KGSFAE5B.js +1 -0
  26. package/dist/chunk-LNL64IJZ.js +1 -0
  27. package/dist/chunk-MKD2VCX3.js +32 -0
  28. package/dist/chunk-MKD2VCX3.js.map +1 -0
  29. package/dist/{chunk-7EMDVIZX.js → chunk-N75DEF5J.js} +19 -1
  30. package/dist/chunk-N75DEF5J.js.map +1 -0
  31. package/dist/chunk-P6WOZO7H.js +49 -0
  32. package/dist/chunk-P6WOZO7H.js.map +1 -0
  33. package/dist/chunk-TGBT5XBE.js +1 -0
  34. package/dist/chunk-TGBT5XBE.js.map +1 -0
  35. package/dist/chunk-UEYRTLKE.js +72 -0
  36. package/dist/chunk-UEYRTLKE.js.map +1 -0
  37. package/dist/chunk-WGHNIAF7.js +329 -0
  38. package/dist/chunk-WGHNIAF7.js.map +1 -0
  39. package/dist/chunk-WQ5MPAVC.js +449 -0
  40. package/dist/chunk-WQ5MPAVC.js.map +1 -0
  41. package/dist/{chunk-FPTDATY5.js → chunk-XQAJM2MW.js} +22 -11
  42. package/dist/chunk-XQAJM2MW.js.map +1 -0
  43. package/dist/chunk-YSTEESEG.js +676 -0
  44. package/dist/chunk-YSTEESEG.js.map +1 -0
  45. package/dist/chunk-ZEOKPWUC.js +1165 -0
  46. package/dist/chunk-ZEOKPWUC.js.map +1 -0
  47. package/dist/connector/index.d.ts +182 -3
  48. package/dist/connector/index.js +12 -4
  49. package/dist/core/index.d.ts +5 -3
  50. package/dist/core/index.js +5 -2
  51. package/dist/error/index.d.ts +54 -0
  52. package/dist/error/index.js +8 -0
  53. package/dist/error/index.js.map +1 -0
  54. package/dist/index.d.ts +100 -12
  55. package/dist/index.js +148 -38
  56. package/dist/index.native.d.ts +20 -10
  57. package/dist/index.native.js +148 -39
  58. package/dist/index.web.d.ts +20 -10
  59. package/dist/index.web.js +149 -39
  60. package/dist/maintenance/index.d.ts +118 -0
  61. package/dist/maintenance/index.js +17 -0
  62. package/dist/maintenance/index.js.map +1 -0
  63. package/dist/platform/index.d.ts +16 -1
  64. package/dist/platform/index.js +2 -0
  65. package/dist/platform/index.js.map +1 -1
  66. package/dist/platform/index.native.d.ts +2 -2
  67. package/dist/platform/index.native.js +2 -1
  68. package/dist/platform/index.web.d.ts +1 -1
  69. package/dist/platform/index.web.js +2 -1
  70. package/dist/pol-attachment-queue-C7YNXXhK.d.ts +676 -0
  71. package/dist/provider/index.d.ts +447 -21
  72. package/dist/provider/index.js +33 -13
  73. package/dist/storage/index.d.ts +6 -0
  74. package/dist/storage/index.js +28 -0
  75. package/dist/storage/index.js.map +1 -0
  76. package/dist/storage/index.native.d.ts +6 -0
  77. package/dist/storage/index.native.js +26 -0
  78. package/dist/storage/index.native.js.map +1 -0
  79. package/dist/storage/index.web.d.ts +6 -0
  80. package/dist/storage/index.web.js +26 -0
  81. package/dist/storage/index.web.js.map +1 -0
  82. package/dist/storage/upload/index.d.ts +55 -0
  83. package/dist/storage/upload/index.js +15 -0
  84. package/dist/storage/upload/index.js.map +1 -0
  85. package/dist/storage/upload/index.native.d.ts +57 -0
  86. package/dist/storage/upload/index.native.js +14 -0
  87. package/dist/storage/upload/index.native.js.map +1 -0
  88. package/dist/storage/upload/index.web.d.ts +5 -0
  89. package/dist/storage/upload/index.web.js +14 -0
  90. package/dist/storage/upload/index.web.js.map +1 -0
  91. package/dist/{index-l3iL9Jte.d.ts → supabase-connector-qLm-WHkM.d.ts} +90 -25
  92. package/dist/sync/index.d.ts +288 -23
  93. package/dist/sync/index.js +22 -10
  94. package/dist/types-BVacP54t.d.ts +52 -0
  95. package/dist/types-Bgvx7-E8.d.ts +187 -0
  96. package/dist/{types-afHtE1U_.d.ts → types-CDqWh56B.d.ts} +2 -0
  97. package/package.json +72 -2
  98. package/dist/chunk-32OLICZO.js +0 -1
  99. package/dist/chunk-3AYXHQ4W.js.map +0 -1
  100. package/dist/chunk-5FIMA26D.js +0 -1
  101. package/dist/chunk-62J2DPKX.js.map +0 -1
  102. package/dist/chunk-7EMDVIZX.js.map +0 -1
  103. package/dist/chunk-EJ23MXPQ.js.map +0 -1
  104. package/dist/chunk-FPTDATY5.js.map +0 -1
  105. package/dist/chunk-KCDG2MNP.js +0 -1431
  106. package/dist/chunk-KCDG2MNP.js.map +0 -1
  107. package/dist/chunk-OLHGI472.js +0 -1
  108. package/dist/chunk-PAFBKNL3.js +0 -99
  109. package/dist/chunk-PAFBKNL3.js.map +0 -1
  110. package/dist/chunk-R4YFWQ3Q.js.map +0 -1
  111. package/dist/chunk-V6LJ6MR2.js +0 -740
  112. package/dist/chunk-V6LJ6MR2.js.map +0 -1
  113. package/dist/chunk-VJCL2SWD.js +0 -1
  114. package/dist/failed-upload-store-C0cLxxPz.d.ts +0 -33
  115. /package/dist/{chunk-32OLICZO.js.map → chunk-DGUM43GV.js.map} +0 -0
  116. /package/dist/{chunk-5FIMA26D.js.map → chunk-GKF7TOMT.js.map} +0 -0
  117. /package/dist/{chunk-OLHGI472.js.map → chunk-KGSFAE5B.js.map} +0 -0
  118. /package/dist/{chunk-VJCL2SWD.js.map → chunk-LNL64IJZ.js.map} +0 -0
@@ -1,13 +1,16 @@
1
1
  import { SupabaseClient } from '@supabase/supabase-js';
2
2
  import { QueryClient } from '@tanstack/react-query';
3
- 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';
3
+ 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';
4
4
  import { PlatformAdapter } from '../platform/index.js';
5
- import { C as ConnectorConfig, S as SupabaseConnector, f as ConflictBus } from '../index-l3iL9Jte.js';
6
- import { AttachmentQueueConfig, AttachmentQueue } from '../attachments/index.js';
5
+ import { b as ConnectorConfig, S as SupabaseConnector, g as ConflictBus } from '../supabase-connector-qLm-WHkM.js';
6
+ import { j as PolAttachmentQueueConfig, P as PolAttachmentQueue } from '../pol-attachment-queue-C7YNXXhK.js';
7
7
  import * as react from 'react';
8
- import react__default from 'react';
9
- import { c as SyncControlActions } from '../types-Cd7RhNqf.js';
10
- import '../failed-upload-store-C0cLxxPz.js';
8
+ import react__default, { ReactNode } from 'react';
9
+ import { Schema } from '@powersync/react-native';
10
+ import { R as RemoteStorageAdapter, A as AttachmentUploadHandler } from '../types-Bgvx7-E8.js';
11
+ import { h as BackgroundSyncSystem, c as SyncControlActions } from '../background-sync-ChCXW-EV.js';
12
+ import '@powersync/attachments';
13
+ import '@powersync/common';
11
14
 
12
15
  /**
13
16
  * Provider Types for @pol-studios/powersync
@@ -71,8 +74,16 @@ interface PowerSyncConfig<TSchema = unknown> {
71
74
  connector?: ConnectorConfig;
72
75
  /**
73
76
  * Optional: Attachment queue configuration for offline file caching.
77
+ *
78
+ * @example
79
+ * ```typescript
80
+ * attachments: {
81
+ * source: { table: 'photos', idColumn: 'storage_path' },
82
+ * remoteStorage: supabaseStorageAdapter,
83
+ * }
84
+ * ```
74
85
  */
75
- attachments?: AttachmentQueueConfig;
86
+ attachments?: PolAttachmentQueueConfig;
76
87
  /**
77
88
  * Optional: Sync behavior configuration.
78
89
  */
@@ -124,7 +135,7 @@ interface PowerSyncContextValue<TSchema = unknown> {
124
135
  * The attachment queue instance.
125
136
  * Will be null if attachments are not configured or not initialized.
126
137
  */
127
- attachmentQueue: AttachmentQueue | null;
138
+ attachmentQueue: PolAttachmentQueue | null;
128
139
  /**
129
140
  * Whether the PowerSync database is ready for use.
130
141
  */
@@ -133,6 +144,17 @@ interface PowerSyncContextValue<TSchema = unknown> {
133
144
  * Whether the provider is currently initializing.
134
145
  */
135
146
  isInitializing: boolean;
147
+ /**
148
+ * Whether the attachment queue is ready for use.
149
+ * This is separate from isReady because the attachment queue initializes
150
+ * asynchronously after the database is ready.
151
+ *
152
+ * States:
153
+ * - `false`: Attachment queue is still initializing
154
+ * - `true` with `attachmentQueue !== null`: Ready and available
155
+ * - `true` with `attachmentQueue === null`: Either attachments not configured, OR initialization failed
156
+ */
157
+ attachmentQueueReady: boolean;
136
158
  /**
137
159
  * Error that occurred during initialization, if any.
138
160
  */
@@ -252,10 +274,6 @@ interface SyncStatusContextValue {
252
274
  * Resume automatic retry of failed uploads.
253
275
  */
254
276
  resumeAutoRetry: () => void;
255
- /**
256
- * Manually retry all failed uploads that are ready for retry.
257
- */
258
- retryFailedUploads: () => Promise<void>;
259
277
  }
260
278
  /**
261
279
  * Connection state - changes rarely (on connect/disconnect).
@@ -298,6 +316,17 @@ interface PendingMutationsContextValue {
298
316
  discardPendingMutation: (clientId: number) => Promise<void>;
299
317
  /** Discard all pending mutations */
300
318
  discardAllPendingMutations: () => Promise<void>;
319
+ /**
320
+ * Add a pending mutation to the list.
321
+ * Called by mutation hooks (useDbInsert, useDbUpdate, useDbDelete, useDbUpsert)
322
+ * after a successful write. Includes createdAt timestamp for display.
323
+ */
324
+ addPendingMutation: (entry: CrudEntry) => void;
325
+ /**
326
+ * Remove a pending mutation by its entity ID.
327
+ * Called when a transaction completes sync.
328
+ */
329
+ removePendingMutation: (id: string) => void;
301
330
  }
302
331
  /**
303
332
  * Failed transactions - changes on failures.
@@ -318,8 +347,16 @@ interface FailedTransactionsContextValue {
318
347
  pauseAutoRetry: () => void;
319
348
  /** Resume automatic retry of failed uploads */
320
349
  resumeAutoRetry: () => void;
321
- /** Manually retry all failed uploads */
322
- retryFailedUploads: () => Promise<void>;
350
+ /**
351
+ * Retry a specific failed transaction.
352
+ *
353
+ * This removes the failure from tracking and triggers a sync.
354
+ * The actual CRUD entries remain in PowerSync's queue - this just
355
+ * clears our error tracking so the sync can retry them.
356
+ *
357
+ * If the sync fails to start, the failure is re-recorded.
358
+ */
359
+ retryFailure: (failureId: string) => Promise<void>;
323
360
  }
324
361
  /**
325
362
  * Completed transactions - changes on successful syncs.
@@ -330,6 +367,18 @@ interface CompletedTransactionsContextValue {
330
367
  completedTransactions: CompletedTransaction[];
331
368
  /** Clear the completed transaction history */
332
369
  clearCompletedHistory: () => void;
370
+ /** Clear a specific completed transaction by ID */
371
+ clearCompletedItem: (completedId: string) => void;
372
+ /**
373
+ * Completed transactions that occurred AFTER the last notification display.
374
+ * Use this for toast/banner notifications to avoid showing stale historical counts.
375
+ */
376
+ newCompletedTransactions: CompletedTransaction[];
377
+ /**
378
+ * Mark notifications as seen (updates the lastNotificationTime).
379
+ * Call this when a sync notification is displayed or auto-dismissed.
380
+ */
381
+ markNotificationsAsSeen: () => void;
333
382
  }
334
383
  /**
335
384
  * Sync mode control - changes rarely (user action).
@@ -340,7 +389,18 @@ interface SyncModeContextValue {
340
389
  syncMode: SyncMode;
341
390
  /** Whether sync is currently paused (offline mode) */
342
391
  isPaused: boolean;
343
- /** Set the sync mode */
392
+ /**
393
+ * Whether offline mode was automatically set due to network loss.
394
+ * When true, sync will auto-resume when network returns.
395
+ * When false (user manually chose offline), sync won't auto-resume.
396
+ */
397
+ isAutoOffline: boolean;
398
+ /**
399
+ * Whether the network is currently reachable.
400
+ * This is used as a gate to block uploads even when syncMode is 'push-pull'.
401
+ */
402
+ networkReachable: boolean;
403
+ /** Set the sync mode (manual - won't auto-resume) */
344
404
  setSyncMode: (mode: SyncMode) => Promise<void>;
345
405
  /** Set the force next upload flag */
346
406
  setForceNextUpload: (force: boolean) => void;
@@ -518,7 +578,7 @@ declare const SyncMetricsContext: react.Context<SyncMetricsContextValue>;
518
578
  * }
519
579
  * ```
520
580
  */
521
- declare const AttachmentQueueContext: react.Context<AttachmentQueue>;
581
+ declare const AttachmentQueueContext: react.Context<PolAttachmentQueue>;
522
582
 
523
583
  /**
524
584
  * PowerSyncProvider Component for @pol-studios/powersync
@@ -563,6 +623,313 @@ declare const AttachmentQueueContext: react.Context<AttachmentQueue>;
563
623
  */
564
624
  declare function PowerSyncProvider<TSchema = unknown>({ config, children, onReady, onError, onSyncStatusChange, }: PowerSyncProviderProps<TSchema>): react__default.ReactElement;
565
625
 
626
+ /**
627
+ * Configuration for @pol-studios/db DataLayerProvider integration.
628
+ * This allows OfflineDataProvider to wrap and configure the DataLayerProvider.
629
+ */
630
+ interface DataLayerConfig {
631
+ /**
632
+ * Entity schemas that define tables and relationships.
633
+ * This is passed directly to DataLayerProvider.
634
+ */
635
+ schema: Record<string, unknown>;
636
+ }
637
+ /**
638
+ * Data layer integration configuration.
639
+ */
640
+ interface DataLayerIntegration {
641
+ /** DataLayer configuration */
642
+ config: DataLayerConfig;
643
+ /** Skip rendering DataLayerProvider (default: false) */
644
+ skip?: boolean;
645
+ }
646
+ /**
647
+ * Callbacks for background sync lifecycle events.
648
+ */
649
+ interface BackgroundSyncCallbacks {
650
+ /** Called when background sync starts */
651
+ onSyncStart?: () => void;
652
+ /** Called when background sync completes successfully */
653
+ onSyncComplete?: () => void;
654
+ /** Called when background sync fails */
655
+ onSyncError?: (error: Error) => void;
656
+ }
657
+ /**
658
+ * Background sync configuration.
659
+ */
660
+ interface BackgroundSyncConfig {
661
+ /** Enable background sync */
662
+ enabled: boolean;
663
+ /** Minimum interval between background syncs in minutes (default: 15) */
664
+ minimumInterval?: number;
665
+ /** Callbacks for sync lifecycle events */
666
+ callbacks?: BackgroundSyncCallbacks;
667
+ }
668
+ /**
669
+ * Status reported by background sync.
670
+ * Compatible with the status callback in BackgroundSyncSystem.
671
+ */
672
+ interface BackgroundSyncStatus {
673
+ /** Last successful sync timestamp */
674
+ lastSyncedAt?: Date | null;
675
+ /** Whether currently downloading */
676
+ downloading: boolean;
677
+ /** Whether currently uploading */
678
+ uploading: boolean;
679
+ }
680
+ /**
681
+ * Snapshot of PowerSync sync status for passing to DataLayerProvider.
682
+ */
683
+ interface PowerSyncSyncStatusSnapshot {
684
+ /** Whether initial sync has completed */
685
+ hasSynced: boolean;
686
+ /** Whether connected to the PowerSync service */
687
+ connected: boolean;
688
+ /** Whether currently attempting to connect */
689
+ connecting: boolean;
690
+ /** Whether the device is online (from platform adapter) */
691
+ isOnline: boolean;
692
+ }
693
+ /**
694
+ * Attachment configuration for OfflineDataProvider
695
+ */
696
+ interface OfflineDataAttachmentConfig {
697
+ /** Storage bucket name */
698
+ bucket: string;
699
+ /** Source table for attachments */
700
+ sourceTable: string;
701
+ /** Column containing the storage path/ID */
702
+ idColumn: string;
703
+ /** Optional: Column to order downloads by */
704
+ orderByColumn?: string;
705
+ /** Optional: Filter configuration */
706
+ projectFilter?: {
707
+ foreignKey: string;
708
+ intermediaryTable: string;
709
+ projectForeignKey: string;
710
+ };
711
+ }
712
+ /**
713
+ * Configuration for OfflineDataProvider
714
+ */
715
+ interface OfflineDataProviderConfig {
716
+ /** PowerSync schema definition */
717
+ schema: Schema;
718
+ /** Supabase client instance */
719
+ supabaseClient: SupabaseClient;
720
+ /** React Query client */
721
+ queryClient: QueryClient;
722
+ /** PowerSync service URL (if missing, runs in online-only mode) */
723
+ powerSyncUrl?: string;
724
+ /** Database filename (default: 'powersync.db') */
725
+ dbFilename?: string;
726
+ /** Attachment configuration */
727
+ attachments?: OfflineDataAttachmentConfig;
728
+ /** Platform adapter (created automatically if not provided) */
729
+ platform?: PlatformAdapter;
730
+ /** Custom connector configuration for CRUD handling */
731
+ connector?: {
732
+ /** Schema router function for table-specific schema lookups */
733
+ schemaRouter?: (table: string) => unknown;
734
+ /** Enable conflict detection */
735
+ conflictDetection?: {
736
+ enabled: boolean;
737
+ };
738
+ };
739
+ /** Sync behavior configuration */
740
+ sync?: {
741
+ /** Automatically connect when the provider mounts and there's an authenticated session */
742
+ autoConnect?: boolean;
743
+ /** Enable health monitoring */
744
+ enableHealthMonitoring?: boolean;
745
+ /** Enable metrics collection */
746
+ enableMetrics?: boolean;
747
+ };
748
+ }
749
+ /**
750
+ * Props for OfflineDataProvider
751
+ */
752
+ interface OfflineDataProviderProps {
753
+ /** Provider configuration */
754
+ config: OfflineDataProviderConfig;
755
+ children: ReactNode;
756
+ /**
757
+ * DataLayer configuration for @pol-studios/db integration.
758
+ * When provided, OfflineDataProvider wraps children with DataLayerProvider
759
+ * and automatically bridges PowerSync context to it.
760
+ */
761
+ dataLayer?: DataLayerIntegration;
762
+ /**
763
+ * Background sync configuration.
764
+ * When enabled, sets up background sync system for iOS/Android.
765
+ */
766
+ backgroundSync?: BackgroundSyncConfig;
767
+ /** Skip rendering ConflictProvider (default: false) */
768
+ skipConflictProvider?: boolean;
769
+ /** Skip rendering StorageQueueProvider (default: false) */
770
+ skipStorageQueueProvider?: boolean;
771
+ /** Custom storage adapter (overrides built-in Supabase adapter) */
772
+ storageAdapter?: RemoteStorageAdapter;
773
+ /** Custom upload handler */
774
+ uploadHandler?: AttachmentUploadHandler;
775
+ /** Custom error UI for initialization errors */
776
+ renderInitError?: (error: Error, retry: () => void) => ReactNode;
777
+ /**
778
+ * Custom error UI (alias for renderInitError for backward compatibility)
779
+ * @deprecated Use renderInitError instead
780
+ */
781
+ renderError?: (error: Error, retry: () => void) => ReactNode;
782
+ onReady?: () => void;
783
+ onError?: (error: Error) => void;
784
+ onSyncStatusChange?: (status: PowerSyncSyncStatusSnapshot) => void;
785
+ /**
786
+ * Called when the background sync system is ready.
787
+ * Use this to set up app-level background sync via defineBackgroundSyncTask.
788
+ */
789
+ onBackgroundSyncSystemReady?: (system: BackgroundSyncSystem) => void;
790
+ }
791
+ /**
792
+ * Props for the internal ProviderBridge component.
793
+ */
794
+ interface ProviderBridgeProps {
795
+ children: ReactNode;
796
+ /** Skip ConflictProvider */
797
+ skipConflictProvider?: boolean;
798
+ /** Skip StorageQueueProvider */
799
+ skipStorageQueueProvider?: boolean;
800
+ /** Background sync configuration */
801
+ backgroundSync?: BackgroundSyncConfig;
802
+ /** Callback for background sync system setup */
803
+ onBackgroundSyncSystemReady?: (system: BackgroundSyncSystem | null) => void;
804
+ /** Called once when db becomes ready, with the db instance and initial sync status */
805
+ onDbReady: (db: AbstractPowerSyncDatabase | null, syncStatus: PowerSyncSyncStatusSnapshot) => void;
806
+ /** Called whenever sync status changes after initial readiness */
807
+ onSyncStatusChange: (syncStatus: PowerSyncSyncStatusSnapshot) => void;
808
+ /** Called with the addPendingMutation function once available */
809
+ onAddPendingMutationReady: (add: (entry: CrudEntry) => void) => void;
810
+ /** Called with the removePendingMutation function once available */
811
+ onRemovePendingMutationReady: (remove: (id: string) => void) => void;
812
+ }
813
+
814
+ /**
815
+ * OfflineDataProvider Component for @pol-studios/powersync
816
+ *
817
+ * Batteries-included offline data provider that combines:
818
+ * - PowerSyncProvider for offline-first data sync
819
+ * - DataLayerProvider integration from @pol-studios/db
820
+ * - ConflictProvider for conflict resolution UI
821
+ * - StorageQueueProvider for attachment queue access
822
+ * - Background sync system setup
823
+ * - Error recovery UI with retry capability
824
+ * - Online-only mode fallback (no PowerSync URL)
825
+ *
826
+ * This is the recommended entry point for apps using offline-first data.
827
+ *
828
+ * @example
829
+ * ```tsx
830
+ * <OfflineDataProvider
831
+ * config={{
832
+ * schema: AppSchema,
833
+ * supabaseClient: supabase,
834
+ * queryClient: queryClient,
835
+ * powerSyncUrl: env.powerSyncUrl,
836
+ * attachments: {
837
+ * bucket: 'my-bucket',
838
+ * sourceTable: 'MediaContent',
839
+ * idColumn: 'storagePath',
840
+ * },
841
+ * }}
842
+ * dataLayer={{ config: dataLayerConfig }}
843
+ * renderInitError={(error, retry) => <MyErrorUI error={error} onRetry={retry} />}
844
+ * >
845
+ * <App />
846
+ * </OfflineDataProvider>
847
+ * ```
848
+ */
849
+
850
+ /**
851
+ * Batteries-included offline data provider.
852
+ *
853
+ * Combines PowerSyncProvider with error boundary, DataLayerProvider integration,
854
+ * and sensible defaults for a complete offline-first data solution.
855
+ *
856
+ * Key features:
857
+ * - Automatic PowerSync setup and initialization
858
+ * - Integration with @pol-studios/db DataLayerProvider
859
+ * - ConflictProvider and StorageQueueProvider wiring
860
+ * - Background sync system support
861
+ * - Error recovery UI with retry capability
862
+ * - Online-only mode fallback when no PowerSync URL is provided
863
+ *
864
+ * @example
865
+ * ```tsx
866
+ * // Basic usage
867
+ * <OfflineDataProvider
868
+ * config={{
869
+ * schema: AppSchema,
870
+ * supabaseClient: supabase,
871
+ * queryClient: queryClient,
872
+ * powerSyncUrl: process.env.EXPO_PUBLIC_POWERSYNC_URL,
873
+ * }}
874
+ * >
875
+ * <App />
876
+ * </OfflineDataProvider>
877
+ *
878
+ * // With DataLayer integration
879
+ * <OfflineDataProvider
880
+ * config={{ ... }}
881
+ * dataLayer={{ config: dataLayerConfig }}
882
+ * >
883
+ * <App />
884
+ * </OfflineDataProvider>
885
+ *
886
+ * // With custom error UI
887
+ * <OfflineDataProvider
888
+ * config={{ ... }}
889
+ * renderInitError={(error, retry) => <MyErrorUI error={error} onRetry={retry} />}
890
+ * >
891
+ * <App />
892
+ * </OfflineDataProvider>
893
+ * ```
894
+ */
895
+ declare function OfflineDataProvider({ config, children, dataLayer, backgroundSync, skipConflictProvider, skipStorageQueueProvider, storageAdapter: customStorageAdapter, uploadHandler: customUploadHandler, renderInitError, renderError, onReady, onError, onSyncStatusChange, onBackgroundSyncSystemReady: onBackgroundSyncSystemReadyProp, }: OfflineDataProviderProps): react__default.ReactElement;
896
+
897
+ /**
898
+ * ProviderBridge Component for @pol-studios/powersync
899
+ *
900
+ * Internal bridge component that connects PowerSync context to external providers:
901
+ * - DataLayerProvider from @pol-studios/db
902
+ * - ConflictProvider from @pol-studios/db
903
+ * - StorageQueueProvider from @pol-studios/db
904
+ *
905
+ * This component is used internally by OfflineDataProvider and should not be
906
+ * exported directly. It handles the complex wiring between packages.
907
+ */
908
+
909
+ /**
910
+ * ProviderBridge connects the PowerSync package context to external providers
911
+ * like ConflictProvider and StorageQueueProvider from @pol-studios/db.
912
+ *
913
+ * This component:
914
+ * 1. Signals the parent when the db is ready (onDbReady)
915
+ * 2. Reports sync status changes (onSyncStatusChange)
916
+ * 3. Exposes pending mutation functions to parent (for DataLayerProvider)
917
+ * 4. Sets up background sync system when enabled
918
+ * 5. Wraps children with ConflictProvider and StorageQueueProvider
919
+ * 6. Exposes PowerSync db via native PowerSyncContext for SDK hooks
920
+ *
921
+ * IMPORTANT: DataLayerProvider is rendered OUTSIDE this component (in OfflineDataProvider)
922
+ * so it always exists in the React tree even before PowerSync is ready.
923
+ * This prevents "useDataLayer must be used within a DataLayerProvider" errors
924
+ * when routes mount before the db is initialized.
925
+ *
926
+ * CRITICAL: The conflictBus is created internally by PowerSyncProvider and
927
+ * passed to the connector. We MUST use the same bus instance from context
928
+ * for ConflictProvider, otherwise conflicts detected by the connector won't
929
+ * reach the UI components subscribed via ConflictProvider.
930
+ */
931
+ declare function ProviderBridge({ children, skipConflictProvider, skipStorageQueueProvider, backgroundSync, onBackgroundSyncSystemReady, onDbReady, onSyncStatusChange, onAddPendingMutationReady, onRemovePendingMutationReady, }: ProviderBridgeProps): react__default.ReactElement | null;
932
+
566
933
  /**
567
934
  * Hook to access the PowerSync database and related services.
568
935
  *
@@ -584,7 +951,17 @@ declare function PowerSyncProvider<TSchema = unknown>({ config, children, onRead
584
951
  */
585
952
  declare function usePowerSync<TSchema = unknown>(): PowerSyncContextValue<TSchema>;
586
953
  /**
587
- * Hook to access the current sync status.
954
+ * @deprecated This hook causes re-renders on any status change.
955
+ * Use focused hooks instead:
956
+ *
957
+ * | Old (useSyncStatus) | New hook |
958
+ * |--------------------------------|-----------------------------|
959
+ * | connected, hasSynced | useConnectionStatus() |
960
+ * | uploading, downloading | useSyncActivityContext() |
961
+ * | pendingCount, pendingMutations | usePendingMutationsContext()|
962
+ * | failedTransactions | useFailedTransactions() |
963
+ * | syncMode, setSyncMode | useSyncMode() |
964
+ * | triggerSync, pause, resume | useSyncControl() |
588
965
  *
589
966
  * @returns Sync status with connection state, pending uploads, and progress
590
967
  * @throws Error if used outside of PowerSyncProvider
@@ -672,11 +1049,11 @@ declare function usePendingMutationsContext(): PendingMutationsContextValue;
672
1049
  * @example
673
1050
  * ```typescript
674
1051
  * function SyncErrorBanner() {
675
- * const { hasUploadErrors, permanentErrorCount, retryFailedUploads } = useFailedTransactionsContext();
1052
+ * const { hasUploadErrors, permanentErrorCount, retryFailure, failedTransactions } = useFailedTransactionsContext();
676
1053
  *
677
1054
  * if (!hasUploadErrors) return null;
678
1055
  * return (
679
- * <Banner onRetry={retryFailedUploads}>
1056
+ * <Banner onRetry={() => failedTransactions.forEach(f => retryFailure(f.id))}>
680
1057
  * {permanentErrorCount} changes failed to sync
681
1058
  * </Banner>
682
1059
  * );
@@ -781,6 +1158,7 @@ declare function useSyncMode(): {
781
1158
  setMode: (mode: SyncMode) => Promise<void>;
782
1159
  canUpload: boolean;
783
1160
  canDownload: boolean;
1161
+ networkReachable: boolean;
784
1162
  };
785
1163
  /**
786
1164
  * Hook to access connection health status.
@@ -865,7 +1243,36 @@ declare function useSyncMetrics(): SyncMetrics;
865
1243
  * }
866
1244
  * ```
867
1245
  */
868
- declare function useAttachmentQueue(): AttachmentQueue | null;
1246
+ declare function useAttachmentQueue(): PolAttachmentQueue | null;
1247
+ /**
1248
+ * Hook to check if the attachment queue has finished initializing.
1249
+ *
1250
+ * This is useful when you need to wait for the attachment queue to be ready
1251
+ * before performing upload operations. The attachment queue initializes
1252
+ * asynchronously after the database is ready, so there's a brief period
1253
+ * where `isReady` is true but `attachmentQueueReady` is false.
1254
+ *
1255
+ * @returns Whether the attachment queue is ready (true if initialized or if attachments not configured)
1256
+ *
1257
+ * @example
1258
+ * ```typescript
1259
+ * function UploadButton() {
1260
+ * const attachmentQueue = useAttachmentQueue();
1261
+ * const attachmentQueueReady = useAttachmentQueueReady();
1262
+ *
1263
+ * if (!attachmentQueueReady) {
1264
+ * return <Button disabled>Initializing...</Button>;
1265
+ * }
1266
+ *
1267
+ * if (!attachmentQueue) {
1268
+ * return <Text>Uploads not configured</Text>;
1269
+ * }
1270
+ *
1271
+ * return <Button onPress={handleUpload}>Upload</Button>;
1272
+ * }
1273
+ * ```
1274
+ */
1275
+ declare function useAttachmentQueueReady(): boolean;
869
1276
  /**
870
1277
  * Hook to get the PowerSync database instance.
871
1278
  * Throws if not ready.
@@ -1090,20 +1497,29 @@ interface SyncActivityResult {
1090
1497
  failed: FailedTransaction[];
1091
1498
  /** Recently completed transactions */
1092
1499
  completed: CompletedTransaction[];
1500
+ /** New completed transactions since last notification display (for toasts/banners) */
1501
+ newCompleted: CompletedTransaction[];
1093
1502
  /** Counts summary */
1094
1503
  counts: {
1095
1504
  pending: number;
1096
1505
  failed: number;
1097
1506
  completed: number;
1507
+ newCompleted: number;
1098
1508
  };
1099
1509
  /** Whether there is any sync activity to show (pending or failed) */
1100
1510
  hasActivity: boolean;
1101
1511
  /** Retry all failed transactions */
1102
1512
  retryAll: () => Promise<void>;
1513
+ /** Retry a specific failed transaction */
1514
+ retryFailure: (failureId: string) => Promise<void>;
1103
1515
  /** Dismiss a specific failure */
1104
1516
  dismissFailure: (failureId: string) => void;
1105
1517
  /** Clear all completed transactions from the list */
1106
1518
  clearCompleted: () => void;
1519
+ /** Clear a specific completed transaction from the list */
1520
+ clearCompletedItem: (completedId: string) => void;
1521
+ /** Mark notifications as seen (for auto-dismiss functionality) */
1522
+ markNotificationsAsSeen: () => void;
1107
1523
  }
1108
1524
  /**
1109
1525
  * Hook to get comprehensive sync activity including pending, failed, and completed transactions.
@@ -1129,5 +1545,15 @@ interface SyncActivityResult {
1129
1545
  * ```
1130
1546
  */
1131
1547
  declare function useSyncActivity(): SyncActivityResult;
1548
+ /**
1549
+ * Get failed transactions state and retry/dismiss functions.
1550
+ * Alias for useFailedTransactionsContext.
1551
+ */
1552
+ declare const useFailedTransactions: typeof useFailedTransactionsContext;
1553
+ /**
1554
+ * Get completed transactions state and clear function.
1555
+ * Alias for useCompletedTransactionsContext.
1556
+ */
1557
+ declare const useCompletedTransactions: typeof useCompletedTransactionsContext;
1132
1558
 
1133
- export { AttachmentQueueContext, CompletedTransactionsContext, type CompletedTransactionsContextValue, ConnectionHealthContext, type ConnectionHealthContextValue, ConnectionStatusContext, type ConnectionStatusContextValue, DEFAULT_CONNECTION_HEALTH, DEFAULT_SYNC_CONFIG, DEFAULT_SYNC_METRICS, DEFAULT_SYNC_STATUS, type EntitySyncStatusResult, FailedTransactionsContext, type FailedTransactionsContextValue, PendingMutationsContext, type PendingMutationsContextValue, type PowerSyncConfig, PowerSyncContext, type PowerSyncContextValue, PowerSyncProvider, type PowerSyncProviderProps, SyncActivityContext, type SyncActivityContextValue, type SyncActivityResult, type SyncConfig, SyncMetricsContext, type SyncMetricsContextValue, SyncModeContext, type SyncModeContextValue, SyncStatusContext, type SyncStatusContextValue, type UploadStatusResult, useAttachmentQueue, useCompletedTransactionsContext, useConnectionHealth, useConnectionStatus, useDatabase, useDownloadProgress, useEntitySyncStatus, useFailedTransactionsContext, useIsSyncing, useOnlineStatus, usePendingMutations, usePendingMutationsContext, usePlatform, usePowerSync, useSyncActivity, useSyncActivityContext, useSyncControl, useSyncMetrics, useSyncMode, useSyncModeContext, useSyncStatus, useUploadStatus };
1559
+ 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 };