@pol-studios/db 1.0.31 → 1.0.34

package/dist/{DataLayerContext-Dc7nF2IG.d.ts → DataLayerContext-BwMk4VpG.d.ts}

@@ -2,7 +2,7 @@ import * as react from 'react';
 import { SupabaseClient } from '@supabase/supabase-js';
 import { QueryClient } from '@tanstack/react-query';
 import { DatabaseSchema, QueryOptions, DataLayerConfig, TableStrategy, SyncStatus, SyncControl } from './core/index.js';
-import { P as PowerSyncDatabase } from './executor-Br27YZvl.js';
+import { P as PowerSyncDatabase } from './executor-YJw4m7Q7.js';
 
 /**
  * V3 Data Layer Adapter Types
@@ -318,6 +318,25 @@ declare class AdapterAutoDetector {
      * @returns Detection result with recommendation and reasoning
      */
     detect(): AutoDetectionResult;
+    /**
+     * Detect backend availability WITHOUT notifying listeners.
+     *
+     * This method is safe to call during React's render phase because it does not
+     * trigger state updates in other components. Use this method when you need to
+     * check backend status synchronously during render (e.g., in getAdapter()).
+     *
+     * The regular detect() method with listener notifications should only be called
+     * from useEffect or event handlers to avoid the React warning:
+     * "Cannot update a component while rendering a different component"
+     *
+     * @returns Detection result with recommendation and reasoning
+     */
+    detectSilent(): AutoDetectionResult;
+    /**
+     * Internal detection logic shared by detect() and detectSilent().
+     * @private
+     */
+    private performDetection;
     /**
      * Check if PowerSync is available.
      *
@@ -342,7 +361,8 @@ declare class AdapterAutoDetector {
      *
      * Prefers the sync status's isOnline property if available (from React Native NetInfo).
      * Falls back to navigator.onLine in browser environments.
-     * Returns true by default for other environments.
+     * Returns false by default for non-browser environments (React Native, Node.js, etc.)
+     * to ensure offline-first behavior works correctly.
      *
      * @returns Whether the device has network connectivity
      */
@@ -431,6 +451,50 @@ declare class AdapterAutoDetector {
  */
 declare function createAdapterAutoDetector(powerSyncDb: PowerSyncDatabase | null, supabase: SupabaseClient | null, options?: AutoDetectorOptions): AdapterAutoDetector;
 
+/**
+ * Minimal interface for sync tracking callbacks.
+ * Intentionally decoupled from the full SyncControl to keep
+ * the adapter layer independent of React context types.
+ */
+interface SyncTracker {
+    addPendingMutation: (entry: {
+        id: string;
+        table: string;
+        op: string;
+        opData?: unknown;
+        createdAt?: Date;
+    }) => void;
+    removePendingMutation: (id: string) => void;
+}
+/**
+ * Decorator that wraps a TableDataAdapter and automatically
+ * tracks pending mutations via SyncTracker callbacks.
+ *
+ * Read operations (query, queryById, subscribe) are passed
+ * through without modification. Mutation operations (insert,
+ * update, upsert, delete) are wrapped with addPendingMutation
+ * before the write and removePendingMutation on error.
+ *
+ * NOTE: The syncTracker can be null/undefined during initialization
+ * due to React's useEffect timing. The adapter handles this gracefully
+ * by using optional chaining - mutations still work, just without tracking.
+ */
+declare class SyncTrackingAdapter implements TableDataAdapter {
+    private readonly inner;
+    private readonly syncTracker;
+    readonly name: string;
+    constructor(inner: TableDataAdapter, syncTracker: SyncTracker | null | undefined);
+    query<T>(table: string, options: QueryOptions): Promise<AdapterQueryResult<T>>;
+    queryById<T>(table: string, id: string, options?: Pick<QueryOptions, "select">): Promise<T | null>;
+    subscribe<T>(table: string, options: QueryOptions, callback: (data: T[]) => void): () => void;
+    insert<T>(table: string, data: Partial<T>): Promise<T>;
+    update<T>(table: string, id: string, data: Partial<T>): Promise<T>;
+    upsert<T>(table: string, data: Partial<T>): Promise<T>;
+    delete(table: string, id: string): Promise<void>;
+    /** Get the underlying unwrapped adapter */
+    getInnerAdapter(): TableDataAdapter;
+}
+
 /**
  * V3 Data Layer Adapter Registry
  *
@@ -489,6 +553,14 @@ declare class AdapterRegistry {
      * Auto-detector instance for automatic backend selection
      */
     private autoDetector;
+    /**
+     * Sync tracker for mutation tracking
+     */
+    private syncTracker;
+    /**
+     * Sync tracking adapter that wraps PowerSync adapter
+     */
+    private syncTrackingAdapter;
     /**
      * Listeners for backend change events
      */
@@ -520,6 +592,17 @@ declare class AdapterRegistry {
      * @param adapter - PowerSync adapter implementation
      */
     setPowerSyncAdapter(adapter: TableDataAdapter): void;
+    /**
+     * Set the sync tracker for mutation tracking.
+     * When set, write operations on PowerSync tables will
+     * automatically track pending mutations.
+     *
+     * NOTE: This also clears the adapter cache to ensure any
+     * previously cached adapters (which may have been created
+     * before the sync tracker was available) are recreated
+     * with the new sync tracker on next access.
+     */
+    setSyncTracker(tracker: SyncTracker): void;
     /**
      * Set the Supabase adapter instance
      *
@@ -556,10 +639,11 @@ declare class AdapterRegistry {
      * - Auto-generates PowerSync alias as "CoreProfile" if not explicitly set
      *
      * @param table - The table name (may be schema-qualified like "core.Profile")
+     * @param operation - The operation type: 'read' uses fallback logic during init, 'write' always uses PowerSync for powersync tables
      * @returns The appropriate adapter for the table
      * @throws Error if adapters are not initialized
      */
-    getAdapter(table: string): TableDataAdapter;
+    getAdapter(table: string, operation?: 'read' | 'write'): TableDataAdapter;
     /**
      * Get the PowerSync adapter directly
      *
@@ -748,8 +832,8 @@ interface DataLayerStatus {
 interface DataLayerCoreContextValue {
     /** Adapter registry for getting table adapters */
     registry: AdapterRegistry;
-    /** Get adapter for a specific table */
-    getAdapter: (table: string) => TableDataAdapter;
+    /** Get adapter for a specific table (defaults to 'read' operation) */
+    getAdapter: (table: string, operation?: 'read' | 'write') => TableDataAdapter;
     /** PowerSync database instance (null when not available) */
     powerSync: PowerSyncDatabase | null;
     /** Supabase client (always available) */
@@ -782,8 +866,8 @@ interface DataLayerStatusContextValue {
 interface DataLayerContextValue {
     /** Adapter registry for getting table adapters */
     registry: AdapterRegistry;
-    /** Get adapter for a specific table */
-    getAdapter: (table: string) => TableDataAdapter;
+    /** Get adapter for a specific table (defaults to 'read' operation) */
+    getAdapter: (table: string, operation?: 'read' | 'write') => TableDataAdapter;
     /** PowerSync database instance (null when not available) */
     powerSync: PowerSyncDatabase | null;
     /** Supabase client (always available) */
@@ -822,4 +906,4 @@ declare const DataLayerStatusContext: react.Context<DataLayerStatusContextValue>
  */
 declare const DataLayerContext: react.Context<DataLayerContextValue>;
 
-export { type AdapterQueryResult as A, BackendStatus as B, type CapableDataAdapter as C, DataLayerContext as D, type SyncStatusInfo as S, type TableDataAdapter as T, type AdapterConfig as a, type AdapterFactory as b, type AdapterCapabilities as c, type AdapterDependencies as d, type AdapterStrategyType as e, ADAPTER_STRATEGIES as f, AdapterRegistry as g, createAdapterRegistry as h, AdapterAutoDetector as i, createAdapterAutoDetector as j, type AutoDetectionResult as k, type AutoDetectorOptions as l, type BackendChangeListener as m, DataLayerCoreContext as n, DataLayerStatusContext as o, type DataLayerContextValue as p, type DataLayerCoreContextValue as q, type DataLayerStatusContextValue as r, type DataLayerStatus as s };
+export { type AdapterQueryResult as A, BackendStatus as B, type CapableDataAdapter as C, DataLayerContext as D, type SyncStatusInfo as S, type TableDataAdapter as T, type AdapterConfig as a, type AdapterFactory as b, type AdapterCapabilities as c, type AdapterDependencies as d, type AdapterStrategyType as e, ADAPTER_STRATEGIES as f, AdapterRegistry as g, createAdapterRegistry as h, AdapterAutoDetector as i, createAdapterAutoDetector as j, type AutoDetectionResult as k, type AutoDetectorOptions as l, type BackendChangeListener as m, SyncTrackingAdapter as n, type SyncTracker as o, DataLayerCoreContext as p, DataLayerStatusContext as q, type DataLayerContextValue as r, type DataLayerCoreContextValue as s, type DataLayerStatusContextValue as t, type DataLayerStatus as u };

package/dist/UserMetadataContext-QLIv-mfF.d.ts

@@ -0,0 +1,171 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { User } from '@supabase/supabase-js';
+import { D as Database } from './useSupabase-DSZNeXnF.js';
+
+type ProfileStatus = "active" | "archived" | "suspended";
+interface SimpleProfile {
+    id: string;
+    email?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    fullName?: string | null;
+    status?: ProfileStatus | null;
+    profilePath?: string | null;
+    [key: string]: unknown;
+}
+interface SimpleUserAccess {
+    id: string;
+    userId: string;
+    accessKey: string;
+}
+interface SimpleAuthContextValue {
+    /** Supabase user (from auth session) */
+    user: User | null;
+    /** Profile from PowerSync (local SQLite) */
+    profile: SimpleProfile | null;
+    /** Access keys from PowerSync (local SQLite) */
+    accessKeys: string[];
+    /** Whether auth data is loading */
+    isLoading: boolean;
+    /** Whether profile is archived */
+    isArchived: boolean;
+    /** Whether profile is suspended */
+    isSuspended: boolean;
+    /** Profile status */
+    profileStatus: ProfileStatus | undefined;
+    /**
+     * Check if user has access to a resource.
+     * Supports wildcards: *:*:*, project:*:read, project:123:*
+     *
+     * @example
+     * hasAccess("admin") // exact match
+     * hasAccess("project:123:read") // check specific resource
+     */
+    hasAccess: (accessKey: string) => boolean;
+    /** Sign out the user */
+    signOut: () => Promise<void>;
+}
+/**
+ * Maps permission action strings to numeric levels for comparison.
+ * Higher numbers grant more access.
+ */
+declare function getPermissionLevel(action: string): number;
+/**
+ * Check if a user has at least the required permission level for a resource.
+ * Checks all matching access keys and returns true if any grants sufficient access.
+ *
+ * @param accessKeys - User's access keys
+ * @param resourceType - e.g., "project", "client", "database"
+ * @param resourceId - The ID of the resource
+ * @param requiredAction - e.g., "read", "edit", "admin"
+ */
+declare function hasResourceAccess(accessKeys: string[], resourceType: string, resourceId: string, requiredAction: string): boolean;
+interface SimpleAuthProviderProps {
+    children: ReactNode;
+    /** Supabase user from auth session */
+    user: User | null;
+    /** Profile from PowerSync query */
+    profile: SimpleProfile | null;
+    /** User access records from PowerSync query */
+    userAccess: SimpleUserAccess[] | null;
+    /** Whether the data is loading */
+    isLoading?: boolean;
+    /** Sign out function */
+    onSignOut: () => Promise<void>;
+}
+declare function SimpleAuthProvider({ children, user, profile, userAccess, isLoading, onSignOut, }: SimpleAuthProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access auth state and hasAccess function.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { user, profile, hasAccess, isLoading } = useSimpleAuth();
+ *
+ *   if (isLoading) return <Loading />;
+ *   if (!user) return <Login />;
+ *
+ *   // Check simple access
+ *   if (hasAccess("admin")) {
+ *     return <AdminPanel />;
+ *   }
+ *
+ *   // Check resource access
+ *   if (hasAccess("project:123:edit")) {
+ *     return <Editor />;
+ *   }
+ *
+ *   return <ReadOnlyView />;
+ * }
+ * ```
+ */
+declare function useSimpleAuth(): SimpleAuthContextValue;
+/**
+ * Hook that requires authentication.
+ * Throws if user is not authenticated.
+ *
+ * @example
+ * ```tsx
+ * function ProtectedComponent() {
+ *   const { user, hasAccess } = useRequireAuth();
+ *   // user is guaranteed to be non-null here
+ * }
+ * ```
+ */
+declare function useRequireAuth(): SimpleAuthContextValue & {
+    user: User;
+};
+/**
+ * Hook to check resource-level access with permission levels.
+ *
+ * @example
+ * ```tsx
+ * function ProjectEditor({ projectId }: { projectId: string }) {
+ *   const canEdit = useResourceAccess("project", projectId, "edit");
+ *   const canDelete = useResourceAccess("project", projectId, "admin");
+ *
+ *   return (
+ *     <div>
+ *       <button disabled={!canEdit}>Edit</button>
+ *       <button disabled={!canDelete}>Delete</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useResourceAccess(resourceType: string, resourceId: string | number | undefined, requiredAction: string): boolean;
+declare function useCanView(resourceType: string, resourceId: string | number | undefined): boolean;
+declare function useCanEdit(resourceType: string, resourceId: string | number | undefined): boolean;
+declare function useCanDelete(resourceType: string, resourceId: string | number | undefined): boolean;
+declare function useCanShare(resourceType: string, resourceId: string | number | undefined): boolean;
+
+type UserMetadataRow = Database["core"]["Tables"]["UserMetadata"]["Row"];
+type UserMetadataInsert = Database["core"]["Tables"]["UserMetadata"]["Insert"];
+type UserMetadataUpdate = Database["core"]["Tables"]["UserMetadata"]["Update"];
+interface UserMetadataContextType {
+    metadata: Record<string, string>;
+    isLoading: boolean;
+    error: Error | null;
+    setMetadata: (key: string, value: string) => Promise<void>;
+    getMetadata: (key: string) => string | undefined;
+    removeMetadata: (key: string) => Promise<void>;
+    refreshMetadata: () => Promise<void>;
+}
+declare const userMetadataContext: react.Context<UserMetadataContextType>;
+declare function UserMetadataProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useUserMetadata(): UserMetadataContextType;
+declare function useUserMetadataValue(key: string): string | undefined;
+declare function useSetUserMetadata(): {
+    setMetadata: (key: string, value: string) => Promise<void>;
+    removeMetadata: (key: string) => Promise<void>;
+};
+declare function useUserMetadataState<T>(key: string, defaultValue: T, options?: {
+    serialize?: (value: T) => string;
+    deserialize?: (value: string) => T;
+}): [T, (value: T) => Promise<void>, boolean];
+
+export { type ProfileStatus as P, SimpleAuthProvider as S, type UserMetadataContextType as U, useRequireAuth as a, useResourceAccess as b, useCanView as c, useCanEdit as d, useCanDelete as e, useCanShare as f, getPermissionLevel as g, hasResourceAccess as h, type SimpleAuthProviderProps as i, type SimpleAuthContextValue as j, type SimpleProfile as k, type SimpleUserAccess as l, useSetUserMetadata as m, useUserMetadata as n, useUserMetadataState as o, useUserMetadataValue as p, userMetadataContext as q, type UserMetadataInsert as r, UserMetadataProvider as s, type UserMetadataRow as t, useSimpleAuth as u, type UserMetadataUpdate as v };

package/dist/{UserMetadataContext-B8gVWGMl.d.ts → UserMetadataContext-pQb3A8_Q.d.ts}

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { D as Database } from './useSupabase-DvWVuHHE.js';
+import { D as Database } from './useSupabase-DSZNeXnF.js';
 
 declare function useLiveChangesIndicator(value: any, field: string | undefined): [boolean, string];
 

package/dist/auth/context.d.ts

@@ -1,13 +1,61 @@
-export { P as Profile, a as ProfileStatus, S as SetupAuthContext, b as SetupAuthContextProviderProps, s as setupAuthContext } from '../setupAuthContext-B76nbIP6.js';
+export { j as SimpleAuthContextValue, S as SimpleAuthProvider, i as SimpleAuthProviderProps, k as SimpleProfile, P as SimpleProfileStatus, l as SimpleUserAccess, U as UserMetadataContextType, r as UserMetadataInsert, s as UserMetadataProvider, t as UserMetadataRow, v as UserMetadataUpdate, g as getPermissionLevel, h as hasResourceAccess, a as useRequireAuth, b as useResourceAccess, m as useSetUserMetadata, u as useSimpleAuth, e as useSimpleCanDelete, d as useSimpleCanEdit, f as useSimpleCanShare, c as useSimpleCanView, n as useUserMetadata, o as useUserMetadataState, p as useUserMetadataValue, q as userMetadataContext } from '../UserMetadataContext-QLIv-mfF.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
+import { User } from '@supabase/supabase-js';
+export { P as Profile, a as ProfileStatus, S as SetupAuthContext, b as SetupAuthContextProviderProps, s as setupAuthContext } from '../setupAuthContext-B76nbIP6.js';
 import { d as EntityType, b as EntityPermissionCheck, a as EntityAction } from '../EntityPermissions-DwFt4tUd.js';
-export { U as UserMetadataContextType, e as UserMetadataInsert, f as UserMetadataProvider, g as UserMetadataRow, h as UserMetadataUpdate, u as useSetUserMetadata, a as useUserMetadata, b as useUserMetadataState, c as useUserMetadataValue, d as userMetadataContext } from '../UserMetadataContext-DntmpK41.js';
-import '@supabase/supabase-js';
-import '../useSupabase-DvWVuHHE.js';
+import '../useSupabase-DSZNeXnF.js';
 import '@supabase/supabase-js/dist/module/lib/types.js';
 
+interface PowerSyncDB {
+    getAll: <T>(sql: string, params?: any[]) => Promise<T[]>;
+    getOptional: <T>(sql: string, params?: any[]) => Promise<T | null>;
+    watch: (sql: string, params: any[], options: {
+        onResult: (result: any) => void;
+    }, abortOptions?: {
+        signal: AbortSignal;
+    }) => void;
+}
+interface SupabaseClient {
+    auth: {
+        getUser: () => Promise<{
+            data: {
+                user: User | null;
+            };
+            error: any;
+        }>;
+        getSession: () => Promise<{
+            data: {
+                session: {
+                    user: User;
+                } | null;
+            };
+            error: any;
+        }>;
+        signOut: () => Promise<{
+            error: any;
+        }>;
+        onAuthStateChange: (callback: (event: string, session: any) => void) => {
+            data: {
+                subscription: {
+                    unsubscribe: () => void;
+                };
+            };
+        };
+    };
+}
+interface OfflineAuthProviderProps {
+    children: ReactNode;
+    /** PowerSync database instance */
+    db: PowerSyncDB | null;
+    /** Supabase client for auth */
+    supabase: SupabaseClient;
+    /** Whether PowerSync is ready */
+    isDbReady?: boolean;
+}
+declare function OfflineAuthProvider({ children, db, supabase, isDbReady, }: OfflineAuthProviderProps): react_jsx_runtime.JSX.Element;
+
 interface AuthProviderProps {
     children: ReactNode;
     /**
@@ -45,4 +93,4 @@ declare function PermissionProvider({ children }: {
 }): react_jsx_runtime.JSX.Element;
 declare function usePermissions(): PermissionContextValue;
 
-export { AuthProvider, type AuthProviderProps, type EntityPermissionContextValue, type PermissionContextValue, PermissionProvider, entityPermissionContext, permissionContext, usePermissions };
+export { AuthProvider, type AuthProviderProps, type EntityPermissionContextValue, OfflineAuthProvider, type OfflineAuthProviderProps, type PermissionContextValue, PermissionProvider, entityPermissionContext, permissionContext, usePermissions };

package/dist/auth/context.js

@@ -1,3 +1,16 @@
+import {
+  OfflineAuthProvider,
+  SimpleAuthProvider,
+  getPermissionLevel,
+  hasResourceAccess,
+  useCanDelete,
+  useCanEdit,
+  useCanShare,
+  useCanView,
+  useRequireAuth,
+  useResourceAccess,
+  useSimpleAuth
+} from "../chunk-5HJLTYRA.js";
 import {
   AuthProvider,
   PermissionProvider,
@@ -11,24 +24,33 @@ import {
   useUserMetadataState,
   useUserMetadataValue,
   userMetadataContext
-} from "../chunk-WX4ABYIF.js";
-import "../chunk-VGEMLNNM.js";
-import "../chunk-GC3TBUWE.js";
+} from "../chunk-67HMVGV7.js";
+import "../chunk-UBHORKBS.js";
 import "../chunk-J4ZVCXZ4.js";
-import "../chunk-OQ7U6EQ3.js";
-import "../chunk-H6365JPC.js";
-import "../chunk-3PJTNH2L.js";
-import "../chunk-5EFDS7SR.js";
-import "../chunk-P4UZ7IXC.js";
+import "../chunk-YUX6RGLZ.js";
+import "../chunk-AKIRHA4Q.js";
+import "../chunk-DMVUEJG2.js";
+import "../chunk-7D4SUZUM.js";
 export {
   AuthProvider,
+  OfflineAuthProvider,
   PermissionProvider,
+  SimpleAuthProvider,
   UserMetadataProvider,
   entityPermissionContext,
+  getPermissionLevel,
+  hasResourceAccess,
   permissionContext,
   setupAuthContext,
   usePermissions,
+  useRequireAuth,
+  useResourceAccess,
   useSetUserMetadata,
+  useSimpleAuth,
+  useCanDelete as useSimpleCanDelete,
+  useCanEdit as useSimpleCanEdit,
+  useCanShare as useSimpleCanShare,
+  useCanView as useSimpleCanView,
   useUserMetadata,
   useUserMetadataState,
   useUserMetadataValue,

package/dist/auth/guards.d.ts

@@ -2,7 +2,7 @@ import { b as EntityPermissionCheck, a as EntityAction } from '../EntityPermissi
 
 /**
  * Check if a user has access to a specific permission key.
- * Owners bypass all permission checks.
+ * Super-admin key (*:*:*) bypasses all permission checks.
  *
  * @param accessKeys - Array of access keys the user has
  * @param key - The access key to check for
@@ -17,8 +17,8 @@ import { b as EntityPermissionCheck, a as EntityAction } from '../EntityPermissi
  * const canAccess = hasAccess(['admin', 'viewer'], 'admin'); // true
  * const cannotAccess = hasAccess(['viewer'], 'admin'); // false
  *
- * // Owner bypasses all checks
- * const ownerAccess = hasAccess(['owner'], 'any-key'); // true
+ * // Super-admin key bypasses all checks
+ * const superAdminAccess = hasAccess(['*:*:*'], 'any-key'); // true
  *
  * // Empty key always returns true (no permission required)
  * const noKeyRequired = hasAccess(['viewer'], ''); // true
@@ -70,12 +70,12 @@ declare function hasAllAccess(accessKeys: string[] | undefined | null, keys: str
 
 /**
  * Check if a user has entity-level access based on permission check result.
- * Owners (users with 'owner' access key) bypass entity permissions entirely.
+ * Super-admin key (*:*:*) bypasses entity permissions entirely.
  *
  * @param permission - The permission check result from getPermission/usePermission
  * @param action - The action to check for
  * @param options - Additional options for the check
- * @param options.accessKeys - User's access keys (for owner check)
+ * @param options.accessKeys - User's access keys (for super-admin check)
  * @param options.isArchived - Whether the user is archived
  * @param options.isSuspended - Whether the user is suspended
  * @returns boolean - true if user has permission for the action
@@ -86,10 +86,10 @@ declare function hasAllAccess(accessKeys: string[] | undefined | null, keys: str
  * const permission = await getPermission('Project', 123);
  * const canEdit = hasEntityAccess(permission, 'edit');
  *
- * // With owner bypass
- * const canEditAsOwner = hasEntityAccess(permission, 'edit', {
- *   accessKeys: ['owner'],
- * }); // true, owners bypass all checks
+ * // With super-admin bypass
+ * const canEditAsSuperAdmin = hasEntityAccess(permission, 'edit', {
+ *   accessKeys: ['*:*:*'],
+ * }); // true, super-admin bypasses all checks
  *
  * // Check loading state
  * if (permission.isLoading) {

package/dist/auth/guards.js

@@ -7,9 +7,8 @@ import {
   hasEntityAccess,
   isEntityAccessDenied,
   isPermissionLoaded
-} from "../chunk-HAWJTZCK.js";
-import "../chunk-OQ7U6EQ3.js";
-import "../chunk-P4UZ7IXC.js";
+} from "../chunk-RT4O5H2E.js";
+import "../chunk-7D4SUZUM.js";
 export {
   hasAccess,
   hasAllAccess,

package/dist/auth/hooks.d.ts

@@ -1,12 +1,116 @@
 import { User } from '@supabase/supabase-js';
+import { k as SimpleProfile, l as SimpleUserAccess } from '../UserMetadataContext-QLIv-mfF.js';
+export { m as useSetUserMetadata, n as useUserMetadata, o as useUserMetadataState, p as useUserMetadataValue } from '../UserMetadataContext-QLIv-mfF.js';
 import { S as SetupAuthContext, E as EffectivePermission } from '../setupAuthContext-B76nbIP6.js';
 import { d as EntityType, a as EntityAction, b as EntityPermissionCheck } from '../EntityPermissions-DwFt4tUd.js';
-export { u as useSetUserMetadata, a as useUserMetadata, b as useUserMetadataState, c as useUserMetadataValue } from '../UserMetadataContext-DntmpK41.js';
-import 'react';
 import 'react/jsx-runtime';
-import '../useSupabase-DvWVuHHE.js';
+import 'react';
+import '../useSupabase-DSZNeXnF.js';
 import '@supabase/supabase-js/dist/module/lib/types.js';
 
+/**
+ * useOfflineAuth - Hook for offline-first authentication
+ *
+ * Reads Profile and UserAccess from PowerSync (local SQLite).
+ * Works 100% offline once data is synced.
+ *
+ * Usage:
+ * ```tsx
+ * import { SimpleAuthProvider } from "@pol-studios/db";
+ * import { useOfflineAuth } from "@pol-studios/db";
+ *
+ * function AuthWrapper({ children }) {
+ *   const authData = useOfflineAuth();
+ *
+ *   return (
+ *     <SimpleAuthProvider {...authData}>
+ *       {children}
+ *     </SimpleAuthProvider>
+ *   );
+ * }
+ * ```
+ */
+
+interface OfflineAuthData {
+    /** Supabase user from auth session */
+    user: User | null;
+    /** Profile from PowerSync */
+    profile: SimpleProfile | null;
+    /** User access records from PowerSync */
+    userAccess: SimpleUserAccess[] | null;
+    /** Whether auth data is loading */
+    isLoading: boolean;
+    /** Sign out function */
+    onSignOut: () => Promise<void>;
+}
+interface UseOfflineAuthOptions {
+    /** Supabase client for auth operations */
+    supabase: {
+        auth: {
+            getUser: () => Promise<{
+                data: {
+                    user: User | null;
+                };
+                error: any;
+            }>;
+            signOut: () => Promise<{
+                error: any;
+            }>;
+            onAuthStateChange: (callback: (event: string, session: any) => void) => {
+                data: {
+                    subscription: {
+                        unsubscribe: () => void;
+                    };
+                };
+            };
+        };
+    };
+    /** PowerSync database for local queries */
+    db: {
+        getAll: <T>(sql: string, params?: any[]) => Promise<T[]>;
+        getOptional: <T>(sql: string, params?: any[]) => Promise<T | null>;
+    } | null;
+    /** Whether PowerSync is ready */
+    isDbReady?: boolean;
+}
+/**
+ * Query keys for React Query integration
+ */
+declare const offlineAuthQueryKeys: {
+    profile: (userId: string | undefined) => readonly ["profile", string];
+    userAccess: (userId: string | undefined) => readonly ["userAccess", string];
+};
+/**
+ * Query functions for React Query integration.
+ * Use these with useQuery from @tanstack/react-query.
+ *
+ * @example
+ * ```tsx
+ * import { useQuery } from "@tanstack/react-query";
+ * import { offlineAuthQueries, offlineAuthQueryKeys } from "@pol-studios/db";
+ *
+ * function useProfile(db, userId) {
+ *   return useQuery({
+ *     queryKey: offlineAuthQueryKeys.profile(userId),
+ *     queryFn: () => offlineAuthQueries.fetchProfile(db, userId),
+ *     enabled: !!userId && !!db,
+ *   });
+ * }
+ * ```
+ */
+declare const offlineAuthQueries: {
+    fetchProfile(db: {
+        getOptional: <T>(sql: string, params?: any[]) => Promise<T | null>;
+    }, userId: string): Promise<SimpleProfile | null>;
+    fetchUserAccess(db: {
+        getAll: <T>(sql: string, params?: any[]) => Promise<T[]>;
+    }, userId: string): Promise<SimpleUserAccess[]>;
+};
+/**
+ * Extract access keys from UserAccess records.
+ */
+declare function extractAccessKeys(userAccess: SimpleUserAccess[] | null): string[];
+
 /**
  * Hook for authenticated users only.
  * Throws an error if the user is not authenticated.
@@ -310,4 +414,4 @@ declare function useInvalidatePermission(): (entityType: EntityType, entityId: n
  */
 declare function usePermissionLoading(): boolean;
 
-export { EntityAction, EntityPermissionCheck, EntityType, type EntityWithPermission, useAuth, useCanCreate, useCanDelete, useCanEdit, useCanShare, useCanView, useInvalidatePermission, usePermission, usePermissionCheck, usePermissionLoading, usePermissionsBatch, useSetupAuth };
+export { EntityAction, EntityPermissionCheck, EntityType, type EntityWithPermission, type OfflineAuthData, type UseOfflineAuthOptions, extractAccessKeys, offlineAuthQueries, offlineAuthQueryKeys, useAuth, useCanCreate, useCanDelete, useCanEdit, useCanShare, useCanView, useInvalidatePermission, usePermission, usePermissionCheck, usePermissionLoading, usePermissionsBatch, useSetupAuth };