@pol-studios/db 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,434 @@
+# @pol-studios/db
+
+> Database layer for React applications with Supabase and PowerSync support
+
+A comprehensive database abstraction layer supporting both Supabase (V2 hooks) and PowerSync (V3 hooks) for offline-first applications. Provides React Query integration, realtime subscriptions, mutation hooks, and storage utilities.
+
+## Installation
+
+```bash
+pnpm add @pol-studios/db
+```
+
+## Peer Dependencies
+
+```bash
+# Required
+pnpm add react @supabase/supabase-js @tanstack/react-query @pol-studios/auth @pol-studios/hooks
+
+# Optional (for React Native / offline-first)
+pnpm add @powersync/react-native @react-native-community/netinfo react-native
+```
+
+## Quick Start
+
+```tsx
+import { SupabaseProvider, useDbQuery, useDbInsert, useDbUpdate, useDbDelete } from "@pol-studios/db";
+
+// Wrap your app with the provider
+function App() {
+  return (
+    <SupabaseProvider url={SUPABASE_URL} anonKey={SUPABASE_ANON_KEY}>
+      <QueryClientProvider client={queryClient}>
+        <MyApp />
+      </QueryClientProvider>
+    </SupabaseProvider>
+  );
+}
+
+// Query data
+function ProjectList() {
+  const { data, isLoading } = useDbQuery("projects", {
+    select: "*",
+    order: { column: "created_at", ascending: false },
+  });
+
+  if (isLoading) return <Loading />;
+  return <List items={data} />;
+}
+
+// Mutations
+function CreateProject() {
+  const insert = useDbInsert("projects");
+  const update = useDbUpdate("projects");
+  const remove = useDbDelete("projects");
+
+  const handleCreate = () => {
+    insert.mutate({ name: "New Project", status: "active" });
+  };
+
+  const handleUpdate = (id, data) => {
+    update.mutate({ id, ...data });
+  };
+
+  const handleDelete = (id) => {
+    remove.mutate({ id });
+  };
+}
+```
+
+## Subpath Exports
+
+| Path | Description |
+|------|-------------|
+| `@pol-studios/db` | All exports combined |
+| `@pol-studios/db/client` | Supabase client utilities |
+| `@pol-studios/db/core` | Core types and configuration |
+| `@pol-studios/db/query` | Query system utilities |
+| `@pol-studios/db/mutation` | Mutation hooks (batch operations) |
+| `@pol-studios/db/realtime` | Realtime subscription utilities |
+| `@pol-studios/db/parser` | Query parser utilities |
+| `@pol-studios/db/hooks` | V3 hooks (PowerSync) |
+| `@pol-studios/db/types` | TypeScript type definitions |
+| `@pol-studios/db/gen` | Generated entity configurations |
+
+## API Reference
+
+### V2 Hooks (Supabase-based)
+
+```tsx
+import {
+  // Query hooks
+  useDbQuery,
+  useDbInfiniteQuery,
+  useDbAdvanceQuery,
+  useDbPartialQuery,
+  useDbRealtimeQuery,
+
+  // Mutation hooks
+  useDbInsert,
+  useDbUpdate,
+  useDbDelete,
+  useDbUpsert,
+  useDbMultiUpsert,
+  useDbMultiDelete,
+
+  // Batch mutations
+  useBatchUpsert,
+  useBatchDelete,
+} from "@pol-studios/db";
+
+// Basic query
+const { data } = useDbQuery("projects", {
+  select: "id, name, status",
+  filter: { status: "active" },
+  order: { column: "name" },
+  limit: 10,
+});
+
+// Infinite scroll query
+const { data, fetchNextPage, hasNextPage } = useDbInfiniteQuery("projects", {
+  select: "*",
+  pageSize: 20,
+});
+
+// Advanced query with joins
+const { data } = useDbAdvanceQuery("projects", {
+  select: "*, tasks(*), owner:profiles(*)",
+  filter: { archived: false },
+});
+
+// Realtime query (auto-updates on changes)
+const { data } = useDbRealtimeQuery("projects", {
+  select: "*",
+  filter: { team_id: teamId },
+});
+
+// Insert with automatic cache invalidation
+const { mutate: insert } = useDbInsert("projects");
+insert({ name: "New Project" });
+
+// Update
+const { mutate: update } = useDbUpdate("projects");
+update({ id: projectId, name: "Updated Name" });
+
+// Upsert
+const { mutate: upsert } = useDbUpsert("projects");
+upsert({ id: projectId, name: "Name" }); // Insert or update
+
+// Batch operations
+const { mutate: batchUpsert } = useBatchUpsert("projects");
+batchUpsert(projectsArray);
+```
+
+### V3 Hooks (PowerSync / Offline-first)
+
+```tsx
+import {
+  // V3 Query hooks
+  useDbQueryV3,
+  useDbQueryById,
+  useDbInfiniteQueryV3,
+  useDbCountV3,
+  useAdvanceQuery,
+
+  // V3 Mutation hooks
+  useDbInsertV3,
+  useDbUpdateV3,
+  useDbDeleteV3,
+  useDbUpsertV3,
+
+  // Sync utilities
+  useSyncStatus,
+  useSyncControl,
+  useOnlineStatus,
+  useDataLayer,
+} from "@pol-studios/db";
+
+// V3 queries work offline with PowerSync
+const { data } = useDbQueryV3("projects", {
+  where: { status: "active" },
+  orderBy: { created_at: "desc" },
+});
+
+// Get single item by ID
+const { data: project } = useDbQueryById("projects", projectId);
+
+// Count query
+const { data: count } = useDbCountV3("projects", {
+  where: { status: "active" },
+});
+
+// Sync status
+const { isSyncing, lastSyncTime, pendingChanges } = useSyncStatus();
+
+// Control sync
+const { startSync, stopSync, forceSync } = useSyncControl();
+
+// Online status
+const isOnline = useOnlineStatus();
+```
+
+### Supabase Client
+
+```tsx
+import {
+  useSupabase,
+  SupabaseProvider,
+  createNewSupabaseClient,
+  typedSupabase,
+  onSupabaseInitialized,
+  setDefaultOptions,
+} from "@pol-studios/db";
+
+// Get typed Supabase client
+const supabase = useSupabase();
+
+// Direct client creation
+const client = createNewSupabaseClient(url, key);
+
+// Typed client for specific database schema
+const typed = typedSupabase(client);
+
+// Initialize callback
+onSupabaseInitialized((client) => {
+  console.log("Supabase ready");
+});
+```
+
+### Realtime Subscriptions
+
+```tsx
+import { useDbRealtime, useLiveChangesIndicator, useLiveChangeTracking } from "@pol-studios/db";
+
+// Subscribe to table changes
+useDbRealtime("projects", {
+  event: "INSERT",
+  filter: `team_id=eq.${teamId}`,
+  callback: (payload) => {
+    console.log("New project:", payload.new);
+  },
+});
+
+// Track live changes indicator
+const { hasChanges, changeCount } = useLiveChangesIndicator("projects");
+
+// Track specific changes
+const { changes, clearChanges } = useLiveChangeTracking("projects", projectId);
+```
+
+### Storage
+
+```tsx
+import {
+  useStorageUrl,
+  useStoragePath,
+  useStorageUpload,
+  useStorageUploadWithEntity,
+  useDbUpload,
+} from "@pol-studios/db";
+
+// Get public URL for storage path
+const url = useStorageUrl("avatars", "user-123.png");
+
+// Generate storage path
+const path = useStoragePath("documents", { entityId, fileName });
+
+// Upload file
+const { upload, isUploading, progress } = useStorageUpload("documents");
+await upload(file);
+
+// Upload with entity association
+const { upload } = useStorageUploadWithEntity("attachments", {
+  entityType: "project",
+  entityId: projectId,
+});
+```
+
+### Utility Hooks
+
+```tsx
+import {
+  useAI,
+  useReceiptAI,
+  useServerAvailability,
+  useSearchQuery,
+  useAutosaveState,
+  useBackgroundTask,
+  useToastError,
+  useLatestOperationLog,
+  useConsent,
+  useAccountDeletion,
+  useUserStatus,
+  useDataExport,
+} from "@pol-studios/db";
+
+// AI integration
+const { generate, isLoading } = useAI();
+
+// Receipt AI processing
+const { processReceipt } = useReceiptAI();
+
+// Server availability check
+const isAvailable = useServerAvailability();
+
+// Search with debounce
+const { results, search } = useSearchQuery("projects", { debounce: 300 });
+
+// Autosave state
+const [value, setValue, { isDirty, isSaving }] = useAutosaveState(initial, saveFn);
+
+// Background task
+const { run, isRunning, progress } = useBackgroundTask(asyncFn);
+
+// Error toast integration
+const showError = useToastError();
+```
+
+### Edge Functions
+
+```tsx
+import { useSupabaseFunction } from "@pol-studios/db";
+
+// Call Supabase Edge Functions
+const { invoke, isLoading, data, error } = useSupabaseFunction("process-data");
+await invoke({ input: "value" });
+```
+
+### Data Layer Provider (V3)
+
+```tsx
+import { DataLayerProvider, useDataLayer } from "@pol-studios/db";
+
+// Wrap app for offline-first support
+<DataLayerProvider config={dataLayerConfig}>
+  <App />
+</DataLayerProvider>
+
+// Access data layer
+const { adapter, isReady, syncStatus } = useDataLayer();
+```
+
+## TypeScript Types
+
+```tsx
+import type {
+  // Database types
+  DatabaseTypes,
+  TableNames,
+  PublicTableNames,
+  SchemaNames,
+  SchemaTableNames,
+
+  // Query types
+  QueryOptions,
+  QueryResult,
+  QuerySingleResult,
+  WhereClause,
+  WhereOperators,
+  OrderBy,
+
+  // Mutation types
+  MutationResult,
+  MutationHookResult,
+  DeleteMutationResult,
+  ExtractRow,
+  ExtractInsert,
+  ExtractUpdate,
+
+  // V3 types
+  DataLayerConfig,
+  DataAdapter,
+  SyncStatus,
+  SyncMode,
+  SyncScope,
+  SyncControl,
+  ConnectionConfig,
+
+  // Strategy types
+  SupabaseStrategy,
+  PowerSyncStrategy,
+  HybridStrategy,
+  CachedStrategy,
+  AutoStrategy,
+  TableStrategy,
+
+  // Schema types
+  DatabaseSchema,
+  TableSchema,
+  ColumnInfo,
+  ColumnType,
+  RelationshipInfo,
+  RelationshipType,
+
+  // Supabase types
+  TypedSupabaseClient,
+  SupabaseDatabaseTypes,
+  UserSessionId,
+} from "@pol-studios/db";
+```
+
+## Network Utilities
+
+```tsx
+import {
+  getOnlineStatus,
+  getOnlineStatusSync,
+  initializeNetworkMonitoring,
+  subscribeToNetworkChanges,
+  isReactNative,
+} from "@pol-studios/db";
+
+// Check online status
+const isOnline = await getOnlineStatus();
+const isOnlineSync = getOnlineStatusSync();
+
+// Initialize network monitoring
+initializeNetworkMonitoring();
+
+// Subscribe to network changes
+const unsubscribe = subscribeToNetworkChanges((isOnline) => {
+  console.log("Network:", isOnline ? "online" : "offline");
+});
+```
+
+## Related Packages
+
+- [@pol-studios/auth](../auth) - Authentication (required peer dependency)
+- [@pol-studios/hooks](../hooks) - React hooks (required peer dependency)
+- [@pol-studios/utils](../utils) - Utility functions
+- [@pol-studios/features](../features) - Feature modules (uses db)
+
+## License
+
+UNLICENSED

package/dist/EntityPermissions-DwFt4tUd.d.ts

@@ -0,0 +1,35 @@
+type EntityType = 'Project' | 'Client' | 'ProjectDatabase';
+type EntityPermissionLevel = 'ReadOnly' | 'AdminReadOnly' | 'ReadWrite' | 'Admin';
+type PermissionEffect = 'allow' | 'deny';
+type EntityAction = 'view' | 'adminView' | 'edit' | 'create' | 'delete' | 'share';
+interface EntityPermissionCheck {
+    canView: boolean;
+    canAdminView: boolean;
+    canEdit: boolean;
+    canCreate: boolean;
+    canDelete: boolean;
+    canShare: boolean;
+    permissionLevel: EntityPermissionLevel | null;
+    isLoading: boolean;
+    /** Whether access was explicitly denied */
+    isDenied?: boolean;
+}
+interface EntityAccessRecord {
+    id: number;
+    userId: string;
+    entityType: EntityType;
+    entityId: number;
+    permission: EntityPermissionLevel;
+    /** Permission effect - 'allow' grants access, 'deny' explicitly blocks */
+    effect: PermissionEffect;
+    inheritedFromClientId?: number | null;
+    inheritFromProject?: boolean;
+    /** User ID who granted this permission */
+    grantedBy?: string | null;
+    /** ISO timestamp when permission was granted */
+    grantedAt?: string;
+    /** ISO timestamp when permission expires, null for never */
+    expiresAt?: string | null;
+}
+
+export type { EntityAccessRecord as E, PermissionEffect as P, EntityAction as a, EntityPermissionCheck as b, EntityPermissionLevel as c, EntityType as d };

package/dist/FilterConfig-Bt2Ek74z.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Unified Filter Configuration Type
+ *
+ * This is the canonical type for filter configuration across the codebase.
+ * Replaces both ValueOption and SimpleFilterConfig.
+ */
+type PropertyType = "string" | "number" | "boolean" | "date";
+type ValueForPropertyType<T extends PropertyType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "date" ? Date : never;
+interface TableInfo {
+    tableName: string;
+    schemaName?: string;
+    outputProperty?: string;
+    innerProperty: string;
+    innerCast?: string;
+}
+interface SortConfig {
+    isSortable?: boolean;
+    properties?: string[];
+}
+interface FilterConfigOption<PT extends PropertyType = PropertyType> {
+    display: string;
+    value: ValueForPropertyType<PT>;
+}
+/**
+ * Simple filter clause for WHERE conditions
+ * Used in edge function query building
+ */
+interface WhereFilter {
+    id: string;
+    field: string;
+    op: string;
+    value: string | number | string[] | number[] | boolean | null;
+    not?: boolean;
+}
+/**
+ * WhereClause can be either:
+ * - string: For edge function format like "tagId.eq.5"
+ * - WhereFilter: For complex filter objects
+ */
+type WhereClause = string | WhereFilter;
+/**
+ * Unified FilterConfig - the canonical filter configuration type
+ *
+ * Uses `field` with dot notation for relationships.
+ * Examples: "name", "locationId.name", "locationId.tags.value"
+ */
+interface FilterConfig<EntityType = unknown, PT extends PropertyType = PropertyType> {
+    /**
+     * Field path using dot notation for relationships
+     * Examples: "name", "locationId.name", "locationId.tags.value"
+     */
+    field?: string;
+    /** The property name on the entity */
+    property?: keyof EntityType | string;
+    /** Display label shown in UI */
+    display: string;
+    /**
+     * Data type of the field. Can be inferred from schema when using `field`.
+     */
+    propertyType?: PT;
+    /** Whether this field is searchable via text search (default: true for strings) */
+    searchable?: boolean;
+    /** Additional WHERE clause for relationship filtering */
+    where?: WhereClause;
+    /** Relationship configuration for many-to-one joins */
+    manyToOneTableInfo?: TableInfo & {
+        innerTable?: TableInfo[];
+    };
+    /** Predefined dropdown options */
+    options?: FilterConfigOption<PT>[];
+    /** Sort configuration for this field */
+    sortOptions?: SortConfig;
+    /** Mark as metadata field (custom columns) */
+    isMetadata?: boolean;
+    /** Hide behind "Show More Filters" button */
+    advanced?: boolean;
+    /** Show in "Recommended" section */
+    recommended?: boolean;
+    /** Custom render function for display in filter dropdown */
+    renderOption?: (option: FilterConfig<EntityType, PT>) => string;
+}
+/**
+ * Group of filter configs for organizing filters in UI
+ * Note: Named "Group" to avoid conflict with FilterGroup (AND/OR query groups)
+ */
+interface Group {
+    /** Title displayed for the group (used as 'label' in some contexts) */
+    title: string;
+    /** Optional nesting level for UI rendering */
+    level?: number;
+    /** Hide entire group by default behind "Show More Filters" button */
+    advanced?: boolean;
+    /** Show this group in the "Recommended" section at the top of the filter dropdown */
+    recommended?: boolean;
+    /** Child filter configs or nested groups */
+    children: (FilterConfig | Group)[];
+}
+
+export type { FilterConfigOption as F, Group as G, PropertyType as P, SortConfig as S, TableInfo as T, ValueForPropertyType as V, WhereFilter as W, FilterConfig as a, WhereClause as b };

package/dist/UserMetadataContext-BYYqA6LI.d.ts

@@ -0,0 +1,89 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { User, SignUpWithPasswordCredentials, AuthTokenResponsePassword } from '@supabase/supabase-js';
+import { D as Database } from './useSupabase-pPhUZHcl.js';
+
+type ProfileStatus = "active" | "archived" | "suspended";
+interface SetupAuthContext {
+    user?: User | null | undefined;
+    isLoading: boolean;
+    profile: Profile | null | undefined;
+    access: string[];
+    /** Whether the profile is archived */
+    isArchived: boolean;
+    /** Whether the profile is suspended */
+    isSuspended: boolean;
+    /** The profile status (active, archived, suspended) */
+    profileStatus: ProfileStatus | undefined;
+    registerAsync: (register: SignUpWithPasswordCredentials) => Promise<any>;
+    signInAsync: (username: string, password: string) => Promise<AuthTokenResponsePassword>;
+    signOutAsync: () => Promise<any>;
+    refreshAsync: () => Promise<void>;
+    onSignOut: (action: () => any) => string;
+    removeOnSignOut: (id: string) => any;
+    hasAccess?: (key: string) => boolean;
+}
+interface Profile {
+    id: string;
+    email?: string;
+    fullName?: string;
+    status?: ProfileStatus;
+    UserAccess?: Array<{
+        accessKey: string;
+    }>;
+    [key: string]: any;
+}
+declare const setupAuthContext: react.Context<SetupAuthContext>;
+/**
+ * Props for SetupAuthContextProvider
+ * A simpler provider that takes pre-computed auth state
+ */
+interface SetupAuthContextProviderProps {
+    children: ReactNode;
+    auth: SetupAuthContext;
+}
+/**
+ * Simple provider that takes auth state and provides it via context.
+ * Use this when you already have the auth state and just need to provide it to children.
+ *
+ * @example
+ * ```tsx
+ * const auth = useSetupAuth();
+ * return (
+ *   <SetupAuthContextProvider auth={auth}>
+ *     <MyComponent />
+ *   </SetupAuthContextProvider>
+ * );
+ * ```
+ */
+declare function SetupAuthContextProvider({ children, auth, }: SetupAuthContextProviderProps): react_jsx_runtime.JSX.Element;
+
+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, SetupAuthContextProvider as S, type UserMetadataContextType as U, type SetupAuthContext as a, type SetupAuthContextProviderProps as b, type Profile as c, useUserMetadata as d, useUserMetadataState as e, useUserMetadataValue as f, userMetadataContext as g, type UserMetadataInsert as h, UserMetadataProvider as i, type UserMetadataRow as j, type UserMetadataUpdate as k, setupAuthContext as s, useSetUserMetadata as u };

package/dist/auth/context.d.ts

@@ -0,0 +1,47 @@
+export { c as Profile, P as ProfileStatus, a as SetupAuthContext, S as SetupAuthContextProvider, b as SetupAuthContextProviderProps, U as UserMetadataContextType, h as UserMetadataInsert, i as UserMetadataProvider, j as UserMetadataRow, k as UserMetadataUpdate, s as setupAuthContext, u as useSetUserMetadata, d as useUserMetadata, e as useUserMetadataState, f as useUserMetadataValue, g as userMetadataContext } from '../UserMetadataContext-BYYqA6LI.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { d as EntityType, b as EntityPermissionCheck, a as EntityAction } from '../EntityPermissions-DwFt4tUd.js';
+import '@supabase/supabase-js';
+import '../useSupabase-pPhUZHcl.js';
+import '@supabase/supabase-js/dist/module/lib/types.js';
+
+interface AuthProviderProps {
+    children: ReactNode;
+    /**
+     * Enable entity-level permissions system (Project, Client, ProjectDatabase access control).
+     * When enabled, wraps children with PermissionProvider.
+     * @default false
+     */
+    enableEntityPermissions?: boolean;
+}
+declare function AuthProvider({ children, enableEntityPermissions, }: AuthProviderProps): react_jsx_runtime.JSX.Element;
+
+interface EntityIdentifier {
+    entityType: EntityType;
+    entityId: number;
+}
+interface PermissionContextValue {
+    getPermission: (entityType: EntityType, entityId: number) => EntityPermissionCheck;
+    checkPermission: (entityType: EntityType, entityId: number, action: EntityAction) => boolean;
+    prefetchPermissions: (entities: EntityIdentifier[]) => Promise<void>;
+    invalidatePermission: (entityType: EntityType, entityId: number) => void;
+    isLoading: boolean;
+}
+/**
+ * @deprecated Use permissionContext instead
+ */
+interface EntityPermissionContextValue extends PermissionContextValue {
+}
+declare const permissionContext: react.Context<PermissionContextValue>;
+/**
+ * @deprecated Use permissionContext instead
+ */
+declare const entityPermissionContext: react.Context<PermissionContextValue>;
+declare function PermissionProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function usePermissions(): PermissionContextValue;
+
+export { AuthProvider, type AuthProviderProps, type EntityPermissionContextValue, type PermissionContextValue, PermissionProvider, entityPermissionContext, permissionContext, usePermissions };