@pol-studios/powersync 1.0.7 → 1.0.11

package/dist/chunk-ZM4ENYMF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/attachments/query-builder.ts","../src/attachments/migration.ts"],"sourcesContent":["/**\n * Query Builder for Attachment Watch Queries\n *\n * Generates SQL queries from WatchConfig objects.\n * Provides type-safe query generation without raw SQL strings.\n */\n\nimport type { WatchConfig } from './types';\n\n// ─── SQL Identifier Validation ────────────────────────────────────────────────\n\n/**\n * Valid SQL identifier pattern.\n * Allows alphanumeric characters and underscores, must start with letter or underscore.\n */\nconst VALID_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\n\n/**\n * SQL reserved words that cannot be used as identifiers (subset of common ones).\n */\nconst SQL_RESERVED_WORDS = new Set(['SELECT', 'FROM', 'WHERE', 'ORDER', 'BY', 'AND', 'OR', 'NOT', 'NULL', 'INSERT', 'UPDATE', 'DELETE', 'DROP', 'CREATE', 'TABLE', 'INDEX', 'JOIN', 'LEFT', 'RIGHT', 'INNER', 'OUTER', 'ON', 'AS', 'DISTINCT', 'GROUP', 'HAVING', 'LIMIT', 'OFFSET', 'UNION', 'EXCEPT', 'INTERSECT', 'IN', 'BETWEEN', 'LIKE', 'IS', 'TRUE', 'FALSE', 'CASE', 'WHEN', 'THEN', 'ELSE', 'END', 'ASC', 'DESC', 'NULLS', 'FIRST', 'LAST']);\n\n/**\n * Validates that a string is a safe SQL identifier.\n * Throws an error if the identifier is invalid or potentially dangerous.\n *\n * @param identifier - The identifier to validate\n * @param context - Description of where this identifier is used (for error messages)\n * @throws Error if identifier is invalid\n */\nexport function validateSqlIdentifier(identifier: string, context: string): void {\n  if (!identifier || typeof identifier !== 'string') {\n    throw new Error(`Invalid ${context}: must be a non-empty string`);\n  }\n  if (!VALID_IDENTIFIER_PATTERN.test(identifier)) {\n    throw new Error(`Invalid ${context}: \"${identifier}\" contains invalid characters. ` + `Identifiers must start with a letter or underscore and contain only alphanumeric characters and underscores.`);\n  }\n  if (SQL_RESERVED_WORDS.has(identifier.toUpperCase())) {\n    throw new Error(`Invalid ${context}: \"${identifier}\" is a SQL reserved word. ` + `Use a different name or quote the identifier.`);\n  }\n\n  // Additional safety: check for SQL injection patterns\n  const dangerousPatterns = [/--/,\n  // SQL comment\n  /;/,\n  // Statement terminator\n  /'/,\n  // String delimiter\n  /\"/,\n  // Quote\n  /\\\\/ // Escape character\n  ];\n  for (const pattern of dangerousPatterns) {\n    if (pattern.test(identifier)) {\n      throw new Error(`Invalid ${context}: \"${identifier}\" contains potentially dangerous characters.`);\n    }\n  }\n}\n\n/**\n * Validates a WHERE clause fragment for basic safety.\n * Note: This is a best-effort validation. Complex WHERE clauses should be reviewed.\n *\n * @param whereClause - The WHERE clause fragment to validate\n * @throws Error if the clause contains dangerous patterns\n */\nexport function validateWhereClause(whereClause: string): void {\n  if (!whereClause || typeof whereClause !== 'string') {\n    throw new Error('Invalid WHERE clause: must be a non-empty string');\n  }\n\n  // Check for dangerous patterns\n  const dangerousPatterns = [{\n    pattern: /;\\s*(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE)/i,\n    name: 'SQL injection (statement)'\n  }, {\n    pattern: /UNION\\s+(ALL\\s+)?SELECT/i,\n    name: 'UNION injection'\n  }, {\n    pattern: /--/,\n    name: 'SQL comment'\n  }, {\n    pattern: /\\/\\*/,\n    name: 'block comment'\n  }, {\n    pattern: /xp_|sp_|exec\\s*\\(/i,\n    name: 'stored procedure'\n  }];\n  for (const {\n    pattern,\n    name\n  } of dangerousPatterns) {\n    if (pattern.test(whereClause)) {\n      throw new Error(`Invalid WHERE clause: contains ${name}`);\n    }\n  }\n}\n\n// ─── Query Builder ────────────────────────────────────────────────────────────\n\n/**\n * Build a SQL watch query from a WatchConfig.\n *\n * Generates a SELECT statement that:\n * - Selects the ID column (aliased as `id`)\n * - Optionally selects additional columns\n * - Applies an optional WHERE clause\n * - Optionally orders by a column\n *\n * @param config - The WatchConfig to build a query from\n * @returns SQL query string\n *\n * @example\n * ```typescript\n * const query = buildWatchQuery({\n *   table: 'EquipmentUnitMediaContent',\n *   idColumn: 'storagePath',\n *   selectColumns: ['equipmentUnitId', 'takenOn'],\n *   where: 'storagePath IS NOT NULL',\n *   orderBy: { column: 'takenOn', direction: 'DESC' },\n * });\n *\n * // Result:\n * // SELECT storagePath AS id, equipmentUnitId, takenOn\n * // FROM EquipmentUnitMediaContent\n * // WHERE storagePath IS NOT NULL\n * // ORDER BY takenOn DESC\n * ```\n */\nexport function buildWatchQuery(config: WatchConfig): string {\n  // Validate all identifiers\n  validateSqlIdentifier(config.table, 'table');\n  validateSqlIdentifier(config.idColumn, 'idColumn');\n  if (config.selectColumns) {\n    for (const col of config.selectColumns) {\n      validateSqlIdentifier(col, 'selectColumns');\n    }\n  }\n  if (config.orderBy) {\n    validateSqlIdentifier(config.orderBy.column, 'orderBy.column');\n    if (config.orderBy.direction !== 'ASC' && config.orderBy.direction !== 'DESC') {\n      throw new Error(`Invalid orderBy.direction: must be \"ASC\" or \"DESC\"`);\n    }\n  }\n  if (config.where) {\n    validateWhereClause(config.where);\n  }\n\n  // Build SELECT clause\n  const selectParts: string[] = [`${config.idColumn} AS id`];\n  if (config.selectColumns && config.selectColumns.length > 0) {\n    selectParts.push(...config.selectColumns);\n  }\n  const selectClause = selectParts.join(', ');\n\n  // Build FROM clause\n  const fromClause = config.table;\n\n  // Build WHERE clause\n  let whereClause = `${config.idColumn} IS NOT NULL AND ${config.idColumn} != ''`;\n  if (config.where) {\n    whereClause = `${whereClause} AND (${config.where})`;\n  }\n\n  // Build ORDER BY clause\n  let orderByClause = '';\n  if (config.orderBy) {\n    orderByClause = `ORDER BY ${config.orderBy.column} ${config.orderBy.direction}`;\n  }\n\n  // Assemble query\n  const parts = [`SELECT ${selectClause}`, `FROM ${fromClause}`, `WHERE ${whereClause}`];\n  if (orderByClause) {\n    parts.push(orderByClause);\n  }\n  return parts.join('\\n');\n}\n\n/**\n * Build a simpler ID-only watch query.\n * Use this when you only need IDs without additional columns.\n *\n * @param config - The WatchConfig to build a query from\n * @returns SQL query string that selects only IDs\n *\n * @example\n * ```typescript\n * const query = buildIdOnlyWatchQuery({\n *   table: 'EquipmentUnitMediaContent',\n *   idColumn: 'storagePath',\n *   where: 'storagePath IS NOT NULL',\n * });\n *\n * // Result:\n * // SELECT storagePath AS id\n * // FROM EquipmentUnitMediaContent\n * // WHERE storagePath IS NOT NULL AND storagePath != ''\n * ```\n */\nexport function buildIdOnlyWatchQuery(config: WatchConfig): string {\n  // Use the full builder but ignore selectColumns\n  return buildWatchQuery({\n    ...config,\n    selectColumns: undefined\n  });\n}\n\n/**\n * Build a query to fetch records with their IDs and additional columns.\n * Used for populating the BatchFilterContext.records map.\n *\n * @param config - The WatchConfig to build a query from\n * @param ids - Optional list of IDs to filter to (for efficiency)\n * @returns SQL query string and parameters\n *\n * @example\n * ```typescript\n * const { query, params } = buildRecordFetchQuery(\n *   {\n *     table: 'EquipmentUnitMediaContent',\n *     idColumn: 'storagePath',\n *     selectColumns: ['equipmentUnitId'],\n *   },\n *   ['path/to/file1.jpg', 'path/to/file2.jpg']\n * );\n * ```\n */\nexport function buildRecordFetchQuery(config: WatchConfig, ids?: string[]): {\n  query: string;\n  params: unknown[];\n} {\n  // Validate identifiers\n  validateSqlIdentifier(config.table, 'table');\n  validateSqlIdentifier(config.idColumn, 'idColumn');\n  if (config.selectColumns) {\n    for (const col of config.selectColumns) {\n      validateSqlIdentifier(col, 'selectColumns');\n    }\n  }\n\n  // Build SELECT clause - always include the ID column\n  const selectParts: string[] = [`${config.idColumn} AS id`];\n  if (config.selectColumns && config.selectColumns.length > 0) {\n    selectParts.push(...config.selectColumns);\n  }\n  const selectClause = selectParts.join(', ');\n\n  // Build query\n  let query = `SELECT ${selectClause} FROM ${config.table}`;\n  const params: unknown[] = [];\n\n  // Add WHERE clause for IDs if provided\n  if (ids && ids.length > 0) {\n    const placeholders = ids.map(() => '?').join(', ');\n    query += ` WHERE ${config.idColumn} IN (${placeholders})`;\n    params.push(...ids);\n  }\n  return {\n    query,\n    params\n  };\n}\n\n/**\n * Convert WatchConfig to the legacy AttachmentSourceConfig format.\n * Useful during migration to maintain backwards compatibility.\n *\n * @param watchConfig - The new WatchConfig\n * @returns Legacy AttachmentSourceConfig\n */\nexport function watchConfigToSourceConfig(watchConfig: WatchConfig): {\n  table: string;\n  idColumn: string;\n  orderByColumn?: string | null;\n} {\n  return {\n    table: watchConfig.table,\n    idColumn: watchConfig.idColumn,\n    orderByColumn: watchConfig.orderBy?.column ?? null\n  };\n}","/**\n * Migration Utilities for @pol-studios/powersync Attachments\n *\n * This module provides utilities for migrating from the old attachment API\n * to the new callback-based API. It includes:\n *\n * - State mapping constants for old → new state transitions\n * - `migrateAttachmentState()` for converting state values\n * - Validation helpers for migration safety\n *\n * @example\n * ```typescript\n * import { migrateAttachmentState, isValidAttachmentState } from '@pol-studios/powersync/attachments';\n *\n * // Migrate a single state value\n * const newState = migrateAttachmentState(oldState);\n *\n * // Validate before migration\n * if (isValidAttachmentState(value)) {\n *   const migrated = migrateAttachmentState(value);\n * }\n * ```\n */\n\nimport { AttachmentState } from '@powersync/attachments';\nimport { PolAttachmentState } from './types';\n\n// ─── State Mapping Constants ──────────────────────────────────────────────────\n\n/**\n * Maps old state values to new state values.\n *\n * The official @powersync/attachments AttachmentState enum has values 0-4:\n *   QUEUED_SYNC=0, QUEUED_UPLOAD=1, QUEUED_DOWNLOAD=2, SYNCED=3, ARCHIVED=4\n *\n * POL extensions add:\n *   FAILED_PERMANENT=5, DOWNLOAD_SKIPPED=6\n *\n * For migration purposes, most states map 1:1. The mapping exists to:\n * 1. Document the relationship between old and new states\n * 2. Provide a clear upgrade path for custom state handling code\n * 3. Allow future state reorganization if needed\n */\nexport const STATE_MAPPING: ReadonlyMap<number, number> = new Map<number, number>([\n// Official states (1:1 mapping)\n[AttachmentState.QUEUED_SYNC as number, PolAttachmentState.QUEUED_SYNC], [AttachmentState.QUEUED_UPLOAD as number, PolAttachmentState.QUEUED_UPLOAD], [AttachmentState.QUEUED_DOWNLOAD as number, PolAttachmentState.QUEUED_DOWNLOAD], [AttachmentState.SYNCED as number, PolAttachmentState.SYNCED], [AttachmentState.ARCHIVED as number, PolAttachmentState.ARCHIVED],\n// POL extension states (identity mapping)\n[PolAttachmentState.FAILED_PERMANENT, PolAttachmentState.FAILED_PERMANENT], [PolAttachmentState.DOWNLOAD_SKIPPED, PolAttachmentState.DOWNLOAD_SKIPPED]]);\n\n/**\n * Human-readable names for attachment states.\n * Useful for logging and debugging during migration.\n */\nexport const STATE_NAMES: ReadonlyMap<number, string> = new Map([[PolAttachmentState.QUEUED_SYNC, 'QUEUED_SYNC'], [PolAttachmentState.QUEUED_UPLOAD, 'QUEUED_UPLOAD'], [PolAttachmentState.QUEUED_DOWNLOAD, 'QUEUED_DOWNLOAD'], [PolAttachmentState.SYNCED, 'SYNCED'], [PolAttachmentState.ARCHIVED, 'ARCHIVED'], [PolAttachmentState.FAILED_PERMANENT, 'FAILED_PERMANENT'], [PolAttachmentState.DOWNLOAD_SKIPPED, 'DOWNLOAD_SKIPPED']]);\n\n/**\n * All valid state values (official + POL extensions).\n */\nexport const VALID_STATES: ReadonlySet<number> = new Set([PolAttachmentState.QUEUED_SYNC, PolAttachmentState.QUEUED_UPLOAD, PolAttachmentState.QUEUED_DOWNLOAD, PolAttachmentState.SYNCED, PolAttachmentState.ARCHIVED, PolAttachmentState.FAILED_PERMANENT, PolAttachmentState.DOWNLOAD_SKIPPED]);\n\n/**\n * States that indicate an active upload workflow.\n * Records in these states should not be migrated to download states.\n */\nexport const UPLOAD_WORKFLOW_STATES: ReadonlySet<number> = new Set([PolAttachmentState.QUEUED_UPLOAD, PolAttachmentState.FAILED_PERMANENT]);\n\n/**\n * States that indicate an active download workflow.\n */\nexport const DOWNLOAD_WORKFLOW_STATES: ReadonlySet<number> = new Set([PolAttachmentState.QUEUED_DOWNLOAD, PolAttachmentState.QUEUED_SYNC]);\n\n/**\n * Terminal states (no further processing needed).\n */\nexport const TERMINAL_STATES: ReadonlySet<number> = new Set([PolAttachmentState.SYNCED, PolAttachmentState.ARCHIVED, PolAttachmentState.DOWNLOAD_SKIPPED]);\n\n// ─── Migration Functions ──────────────────────────────────────────────────────\n\n/**\n * Migrates an attachment state from the old API to the new API.\n *\n * Currently, this is a 1:1 mapping since the state values haven't changed.\n * This function exists to:\n * 1. Provide a clear migration path for apps using custom state handling\n * 2. Document the state relationship\n * 3. Allow future state reorganization without breaking existing code\n *\n * @param oldState - The state value from the old API\n * @returns The corresponding state value in the new API\n * @throws Error if the state value is invalid\n *\n * @example\n * ```typescript\n * import { migrateAttachmentState } from '@pol-studios/powersync/attachments';\n *\n * // Migrate a record's state\n * const newState = migrateAttachmentState(record.state);\n *\n * // Migrate with fallback for unknown states\n * const safeState = isValidAttachmentState(record.state)\n *   ? migrateAttachmentState(record.state)\n *   : PolAttachmentState.QUEUED_SYNC;\n * ```\n */\nexport function migrateAttachmentState(oldState: number): number {\n  const newState = STATE_MAPPING.get(oldState);\n  if (newState === undefined) {\n    throw new Error(`Invalid attachment state: ${oldState}. ` + `Valid states are: ${Array.from(STATE_NAMES.entries()).map(([v, n]) => `${n}(${v})`).join(', ')}`);\n  }\n  return newState;\n}\n\n/**\n * Safely migrates an attachment state with a fallback.\n *\n * Unlike `migrateAttachmentState`, this function never throws.\n * Invalid states are mapped to the provided fallback.\n *\n * @param oldState - The state value from the old API\n * @param fallback - State to use if oldState is invalid (default: QUEUED_SYNC)\n * @returns The corresponding state value in the new API, or the fallback\n *\n * @example\n * ```typescript\n * // Safely migrate with QUEUED_SYNC as fallback\n * const state = migrateAttachmentStateSafe(unknownValue);\n *\n * // Use custom fallback\n * const state = migrateAttachmentStateSafe(unknownValue, PolAttachmentState.ARCHIVED);\n * ```\n */\nexport function migrateAttachmentStateSafe(oldState: number, fallback: number = PolAttachmentState.QUEUED_SYNC): number {\n  const newState = STATE_MAPPING.get(oldState);\n  return newState !== undefined ? newState : fallback;\n}\n\n// ─── Validation Helpers ───────────────────────────────────────────────────────\n\n/**\n * Checks if a value is a valid attachment state.\n *\n * @param value - The value to check\n * @returns true if the value is a valid attachment state\n *\n * @example\n * ```typescript\n * if (isValidAttachmentState(record.state)) {\n *   // Safe to use record.state\n * } else {\n *   console.warn(`Invalid state: ${record.state}`);\n * }\n * ```\n */\nexport function isValidAttachmentState(value: unknown): value is number {\n  return typeof value === 'number' && VALID_STATES.has(value);\n}\n\n/**\n * Checks if a state represents an upload workflow.\n *\n * Records in upload workflow states should not be demoted to download states.\n *\n * @param state - The state to check\n * @returns true if the state is part of an upload workflow\n */\nexport function isUploadWorkflowState(state: number): boolean {\n  return UPLOAD_WORKFLOW_STATES.has(state);\n}\n\n/**\n * Checks if a state represents a download workflow.\n *\n * @param state - The state to check\n * @returns true if the state is part of a download workflow\n */\nexport function isDownloadWorkflowState(state: number): boolean {\n  return DOWNLOAD_WORKFLOW_STATES.has(state);\n}\n\n/**\n * Checks if a state is terminal (no further processing needed).\n *\n * @param state - The state to check\n * @returns true if the state is terminal\n */\nexport function isTerminalState(state: number): boolean {\n  return TERMINAL_STATES.has(state);\n}\n\n/**\n * Gets the human-readable name of a state.\n *\n * @param state - The state value\n * @returns The state name, or \"UNKNOWN\" for invalid states\n *\n * @example\n * ```typescript\n * console.log(`State: ${getStateName(record.state)}`); // \"State: SYNCED\"\n * ```\n */\nexport function getStateName(state: number): string {\n  return STATE_NAMES.get(state) ?? 'UNKNOWN';\n}\n\n// ─── Migration Report ─────────────────────────────────────────────────────────\n\n/**\n * Statistics about a batch migration.\n */\nexport interface MigrationStats {\n  /** Total records processed */\n  total: number;\n  /** Records successfully migrated */\n  migrated: number;\n  /** Records with invalid states (used fallback) */\n  invalid: number;\n  /** Breakdown by state */\n  byState: Map<number, number>;\n}\n\n/**\n * Creates empty migration stats.\n */\nexport function createMigrationStats(): MigrationStats {\n  return {\n    total: 0,\n    migrated: 0,\n    invalid: 0,\n    byState: new Map()\n  };\n}\n\n/**\n * Records a migration result in the stats.\n *\n * @param stats - The stats object to update\n * @param oldState - The original state\n * @param newState - The migrated state\n * @param wasValid - Whether the original state was valid\n */\nexport function recordMigration(stats: MigrationStats, oldState: number, newState: number, wasValid: boolean): void {\n  stats.total++;\n  if (wasValid) {\n    stats.migrated++;\n  } else {\n    stats.invalid++;\n  }\n  stats.byState.set(newState, (stats.byState.get(newState) ?? 0) + 1);\n}\n\n/**\n * Formats migration stats as a human-readable summary.\n *\n * @param stats - The stats to format\n * @returns A formatted string summary\n *\n * @example\n * ```typescript\n * const stats = createMigrationStats();\n * // ... process records ...\n * console.log(formatMigrationStats(stats));\n * // Output:\n * // Migration Summary:\n * //   Total: 100\n * //   Migrated: 98\n * //   Invalid (used fallback): 2\n * //   By State:\n * //     SYNCED: 50\n * //     QUEUED_DOWNLOAD: 30\n * //     QUEUED_UPLOAD: 18\n * //     QUEUED_SYNC: 2\n * ```\n */\nexport function formatMigrationStats(stats: MigrationStats): string {\n  const lines = ['Migration Summary:', `  Total: ${stats.total}`, `  Migrated: ${stats.migrated}`, `  Invalid (used fallback): ${stats.invalid}`, '  By State:'];\n  for (const [state, count] of stats.byState.entries()) {\n    lines.push(`    ${getStateName(state)}: ${count}`);\n  }\n  return lines.join('\\n');\n}"],"mappings":"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","names":[]}

package/dist/connector/index.d.ts

@@ -1,8 +1,61 @@
-export { g as ConflictBus, C as ConnectorCircuitBreakerConfig, b as ConnectorConfig, e as CrudHandler, D as DEFAULT_RETRY_CONFIG, P as PowerSyncCredentials, f as RetryConfig, R as RetryStrategyConfig, c as SchemaRouter, S as SupabaseConnector, a as SupabaseConnectorOptions, d as defaultSchemaRouter } from '../supabase-connector-qLm-WHkM.js';
+import { A as AuthProvider } from '../types-B212hgfA.js';
+export { g as ConflictBus, C as ConnectorCircuitBreakerConfig, a as ConnectorConfig, c as CrudHandler, D as DEFAULT_RETRY_CONFIG, P as PowerSyncCredentials, e as RetryConfig, R as RetryStrategyConfig, b as SchemaRouter, f as Session, S as SupabaseConnectorOptions, d as defaultSchemaRouter } from '../types-B212hgfA.js';
+export { S as SupabaseConnector } from '../supabase-connector-T9vHq_3i.js';
+import { SupabaseClient } from '@supabase/supabase-js';
 export { P as PowerSyncBackendConnector } from '../types-CDqWh56B.js';
-import '@supabase/supabase-js';
 import '../platform/index.js';
 
+/**
+ * Supabase Auth Provider for @pol-studios/powersync
+ *
+ * Factory function that wraps a Supabase client's auth methods
+ * to implement the AuthProvider interface.
+ */
+
+/**
+ * Options for createSupabaseAuth
+ */
+interface SupabaseAuthOptions {
+    /**
+     * Called when a session refresh fails.
+     * Use this to trigger logout flows or show error UI.
+     */
+    onRefreshError?: (error: Error) => void;
+}
+/**
+ * Creates an AuthProvider that wraps Supabase auth.
+ *
+ * @param supabase - Supabase client instance
+ * @param options - Optional configuration
+ * @returns AuthProvider implementation
+ *
+ * @example
+ * ```typescript
+ * import { createSupabaseAuth } from '@pol-studios/powersync';
+ *
+ * const auth = createSupabaseAuth(supabaseClient, {
+ *   onRefreshError: (error) => {
+ *     console.error('Session refresh failed:', error);
+ *     // Navigate to login screen
+ *   },
+ * });
+ *
+ * // Use with PowerSyncProvider
+ * <PowerSyncProvider auth={auth} ... />
+ * ```
+ */
+declare function createSupabaseAuth(supabase: SupabaseClient, options?: SupabaseAuthOptions): AuthProvider;
+/**
+ * Error thrown when session refresh fails.
+ */
+declare class AuthRefreshError extends Error {
+    readonly name = "AuthRefreshError";
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+
 /**
  * Circuit Breaker Pattern for PowerSync Connector
  *
@@ -181,4 +234,4 @@ declare class CircuitBreaker {
     private log;
 }
 
-export { CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerStats, CircuitOpenError, type CircuitState, DEFAULT_CIRCUIT_BREAKER_CONFIG };
+export { AuthProvider, AuthRefreshError, CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerStats, CircuitOpenError, type CircuitState, DEFAULT_CIRCUIT_BREAKER_CONFIG, type SupabaseAuthOptions, createSupabaseAuth };

package/dist/connector/index.js

@@ -1,22 +1,25 @@
 import {
+  AuthRefreshError,
   CircuitBreaker,
   CircuitOpenError,
-  DEFAULT_CIRCUIT_BREAKER_CONFIG
-} from "../chunk-4C3RY5SU.js";
+  DEFAULT_CIRCUIT_BREAKER_CONFIG,
+  createSupabaseAuth
+} from "../chunk-HWSNV45P.js";
 import {
   DEFAULT_RETRY_CONFIG,
   SupabaseConnector,
   defaultSchemaRouter
-} from "../chunk-HFOFLW5F.js";
+} from "../chunk-KN2IZERF.js";
 import "../chunk-FV2HXEIY.js";
-import "../chunk-XQAJM2MW.js";
-import "../chunk-DGUM43GV.js";
+import "../chunk-VACPAAQZ.js";
 export {
+  AuthRefreshError,
   CircuitBreaker,
   CircuitOpenError,
   DEFAULT_CIRCUIT_BREAKER_CONFIG,
   DEFAULT_RETRY_CONFIG,
   SupabaseConnector,
+  createSupabaseAuth,
   defaultSchemaRouter
 };
 //# sourceMappingURL=index.js.map

package/dist/core/index.d.ts

@@ -195,5 +195,16 @@ declare function extractEntityIds(entries: CrudEntry[]): string[];
  * Extract unique table names from CRUD entries.
  */
 declare function extractTableNames(entries: CrudEntry[]): string[];
+/**
+ * Check if an error is an RLS/permission error (PostgreSQL 42501 - insufficient_privilege).
+ *
+ * RLS errors are special because they may resolve when parent data syncs.
+ * For example, inserting a child record may fail until the parent record syncs
+ * and satisfies the RLS policy conditions.
+ *
+ * @param error - The error to check
+ * @returns true if the error is an RLS/permission error
+ */
+declare function isRlsError(error: unknown): boolean;
 
-export { ATTACHMENT_DOWNLOAD_TIMEOUT_MS, ATTACHMENT_RETRY_DELAY_MS, AttachmentError, COMPRESSION_MAX_WIDTH, COMPRESSION_SKIP_SIZE_BYTES, COMPRESSION_TARGET_SIZE_BYTES, ClassifiedError, ConfigurationError, ConnectorError, CrudEntry, DEFAULT_ATTACHMENT_CACHE_SIZE, DEFAULT_ATTACHMENT_CONCURRENCY, DEFAULT_COMPRESSION_QUALITY, DEFAULT_MAX_RETRY_ATTEMPTS, DEFAULT_RETRY_BACKOFF_MULTIPLIER, DEFAULT_RETRY_BASE_DELAY_MS, DEFAULT_RETRY_MAX_DELAY_MS, DEFAULT_SYNC_INTERVAL_MS, DEFAULT_SYNC_MODE, DOWNLOAD_STOP_THRESHOLD, EVICTION_TRIGGER_THRESHOLD, HEALTH_CHECK_INTERVAL_MS, HEALTH_CHECK_TIMEOUT_MS, InitializationError, LATENCY_DEGRADED_THRESHOLD_MS, MAX_CONSECUTIVE_FAILURES, PlatformAdapterError, PowerSyncError, STATS_CACHE_TTL_MS, STATUS_NOTIFY_THROTTLE_MS, STORAGE_CRITICAL_THRESHOLD, STORAGE_KEY_ATTACHMENT_SETTINGS, STORAGE_KEY_AUTO_OFFLINE, STORAGE_KEY_ENABLED, STORAGE_KEY_METRICS, STORAGE_KEY_PAUSED, STORAGE_KEY_PREFIX, STORAGE_KEY_SYNC_MODE, STORAGE_WARNING_THRESHOLD, SyncError, SyncErrorType, SyncOperationError, classifyError, classifySupabaseError, createSyncError, extractEntityIds, extractTableNames, generateFailureId, toSyncOperationError };
+export { ATTACHMENT_DOWNLOAD_TIMEOUT_MS, ATTACHMENT_RETRY_DELAY_MS, AttachmentError, COMPRESSION_MAX_WIDTH, COMPRESSION_SKIP_SIZE_BYTES, COMPRESSION_TARGET_SIZE_BYTES, ClassifiedError, ConfigurationError, ConnectorError, CrudEntry, DEFAULT_ATTACHMENT_CACHE_SIZE, DEFAULT_ATTACHMENT_CONCURRENCY, DEFAULT_COMPRESSION_QUALITY, DEFAULT_MAX_RETRY_ATTEMPTS, DEFAULT_RETRY_BACKOFF_MULTIPLIER, DEFAULT_RETRY_BASE_DELAY_MS, DEFAULT_RETRY_MAX_DELAY_MS, DEFAULT_SYNC_INTERVAL_MS, DEFAULT_SYNC_MODE, DOWNLOAD_STOP_THRESHOLD, EVICTION_TRIGGER_THRESHOLD, HEALTH_CHECK_INTERVAL_MS, HEALTH_CHECK_TIMEOUT_MS, InitializationError, LATENCY_DEGRADED_THRESHOLD_MS, MAX_CONSECUTIVE_FAILURES, PlatformAdapterError, PowerSyncError, STATS_CACHE_TTL_MS, STATUS_NOTIFY_THROTTLE_MS, STORAGE_CRITICAL_THRESHOLD, STORAGE_KEY_ATTACHMENT_SETTINGS, STORAGE_KEY_AUTO_OFFLINE, STORAGE_KEY_ENABLED, STORAGE_KEY_METRICS, STORAGE_KEY_PAUSED, STORAGE_KEY_PREFIX, STORAGE_KEY_SYNC_MODE, STORAGE_WARNING_THRESHOLD, SyncError, SyncErrorType, SyncOperationError, classifyError, classifySupabaseError, createSyncError, extractEntityIds, extractTableNames, generateFailureId, isRlsError, toSyncOperationError };

package/dist/core/index.js

@@ -46,9 +46,9 @@ import {
   extractEntityIds,
   extractTableNames,
   generateFailureId,
+  isRlsError,
   toSyncOperationError
-} from "../chunk-XQAJM2MW.js";
-import "../chunk-DGUM43GV.js";
+} from "../chunk-VACPAAQZ.js";
 export {
   ATTACHMENT_DOWNLOAD_TIMEOUT_MS,
   ATTACHMENT_RETRY_DELAY_MS,
@@ -94,6 +94,7 @@ export {
   extractEntityIds,
   extractTableNames,
   generateFailureId,
+  isRlsError,
   toSyncOperationError
 };
 //# sourceMappingURL=index.js.map

package/dist/error/index.js

@@ -1,7 +1,6 @@
 import {
   PowerSyncErrorBoundary
 } from "../chunk-P6WOZO7H.js";
-import "../chunk-DGUM43GV.js";
 export {
   PowerSyncErrorBoundary
 };