@startsimpli/hooks 0.4.6 → 0.4.8

package/src/__tests__/useWizard.test.ts

@@ -1,10 +1,12 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { renderHook, act } from '@testing-library/react'
 import { useWizard } from '../useWizard'
 
 const STEPS = ['upload', 'mapping', 'importing', 'complete'] as const
 
 describe('useWizard', () => {
+  // ---------- backward compatibility ----------
+
   it('starts on the initial step', () => {
     const { result } = renderHook(() => useWizard(STEPS))
     expect(result.current.currentStep).toBe('upload')
@@ -20,41 +22,41 @@ describe('useWizard', () => {
 
   it('advances to next step', () => {
     const { result } = renderHook(() => useWizard(STEPS))
-    act(() => result.current.next())
+    act(() => { result.current.next() })
     expect(result.current.currentStep).toBe('mapping')
     expect(result.current.stepIndex).toBe(1)
   })
 
   it('goes back to previous step', () => {
     const { result } = renderHook(() => useWizard(STEPS, 'mapping'))
-    act(() => result.current.prev())
+    act(() => { result.current.prev() })
     expect(result.current.currentStep).toBe('upload')
   })
 
   it('does not go before first step', () => {
     const { result } = renderHook(() => useWizard(STEPS))
-    act(() => result.current.prev())
+    act(() => { result.current.prev() })
     expect(result.current.currentStep).toBe('upload')
   })
 
   it('does not go past last step', () => {
     const { result } = renderHook(() => useWizard(STEPS, 'complete'))
-    act(() => result.current.next())
+    act(() => { result.current.next() })
     expect(result.current.currentStep).toBe('complete')
   })
 
   it('goTo navigates to any step', () => {
     const { result } = renderHook(() => useWizard(STEPS))
-    act(() => result.current.goTo('importing'))
+    act(() => { result.current.goTo('importing') })
     expect(result.current.currentStep).toBe('importing')
     expect(result.current.stepIndex).toBe(2)
   })
 
   it('reset returns to initial step', () => {
     const { result } = renderHook(() => useWizard(STEPS))
-    act(() => result.current.next())
-    act(() => result.current.next())
-    act(() => result.current.reset())
+    act(() => { result.current.next() })
+    act(() => { result.current.next() })
+    act(() => { result.current.reset() })
     expect(result.current.currentStep).toBe('upload')
   })
 
@@ -73,4 +75,194 @@ describe('useWizard', () => {
     expect(result.current.canGoBack).toBe(true)
     expect(result.current.canGoNext).toBe(false)
   })
+
+  it('next() returns null when no validation is configured', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    let returnVal: ReturnType<typeof result.current.next>
+    act(() => { returnVal = result.current.next() })
+    expect(returnVal!).toBeNull()
+  })
+
+  it('errors is null by default', () => {
+    const { result } = renderHook(() => useWizard(STEPS))
+    expect(result.current.errors).toBeNull()
+  })
+
+  // ---------- per-step validation ----------
+
+  describe('with validation', () => {
+    const FORM_STEPS = ['details', 'sequence', 'review'] as const
+
+    it('blocks next() when validator returns errors', () => {
+      const validate = {
+        details: () => ({ name: 'Name is required' }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      let errors: Record<string, string> | null
+      act(() => { errors = result.current.next() })
+
+      expect(errors!).toEqual({ name: 'Name is required' })
+      expect(result.current.currentStep).toBe('details')
+      expect(result.current.errors).toEqual({ name: 'Name is required' })
+    })
+
+    it('advances when validator returns null', () => {
+      const validate = {
+        details: () => null,
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      let returnVal: Record<string, string> | null
+      act(() => { returnVal = result.current.next() })
+
+      expect(returnVal!).toBeNull()
+      expect(result.current.currentStep).toBe('sequence')
+      expect(result.current.errors).toBeNull()
+    })
+
+    it('advances when validator returns empty object', () => {
+      const validate = {
+        details: () => ({}),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      act(() => { result.current.next() })
+      expect(result.current.currentStep).toBe('sequence')
+      expect(result.current.errors).toBeNull()
+    })
+
+    it('skips validation for steps without a validator', () => {
+      const validate = {
+        details: () => null,
+        // no validator for 'sequence'
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      // advance past details (has validator returning null)
+      act(() => { result.current.next() })
+      expect(result.current.currentStep).toBe('sequence')
+
+      // advance past sequence (no validator)
+      act(() => { result.current.next() })
+      expect(result.current.currentStep).toBe('review')
+    })
+
+    it('clearErrors resets errors to null', () => {
+      const validate = {
+        details: () => ({ name: 'Required' }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      act(() => { result.current.next() })
+      expect(result.current.errors).toEqual({ name: 'Required' })
+
+      act(() => { result.current.clearErrors() })
+      expect(result.current.errors).toBeNull()
+    })
+
+    it('reset clears errors', () => {
+      const validate = {
+        details: () => ({ name: 'Required' }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      act(() => { result.current.next() })
+      expect(result.current.errors).not.toBeNull()
+
+      act(() => { result.current.reset() })
+      expect(result.current.errors).toBeNull()
+    })
+
+    it('works with initialStep and opts together', () => {
+      const validate = {
+        sequence: () => ({ steps: 'Add at least one step' }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, 'sequence', { validate })
+      )
+
+      expect(result.current.currentStep).toBe('sequence')
+
+      let errors: Record<string, string> | null
+      act(() => { errors = result.current.next() })
+
+      expect(errors!).toEqual({ steps: 'Add at least one step' })
+      expect(result.current.currentStep).toBe('sequence')
+    })
+
+    it('calls the validator for the current step only', () => {
+      const detailsValidator = vi.fn(() => null)
+      const sequenceValidator = vi.fn(() => null)
+
+      const validate = {
+        details: detailsValidator,
+        sequence: sequenceValidator,
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      act(() => { result.current.next() })
+      expect(detailsValidator).toHaveBeenCalledTimes(1)
+      expect(sequenceValidator).not.toHaveBeenCalled()
+
+      act(() => { result.current.next() })
+      expect(sequenceValidator).toHaveBeenCalledTimes(1)
+    })
+
+    it('clears previous errors on successful next()', () => {
+      let shouldFail = true
+      const validate = {
+        details: () => (shouldFail ? { name: 'Required' } : null),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      // First call fails
+      act(() => { result.current.next() })
+      expect(result.current.errors).toEqual({ name: 'Required' })
+      expect(result.current.currentStep).toBe('details')
+
+      // Fix the data, try again
+      shouldFail = false
+      act(() => { result.current.next() })
+      expect(result.current.errors).toBeNull()
+      expect(result.current.currentStep).toBe('sequence')
+    })
+
+    it('returns multiple errors from a single validator', () => {
+      const validate = {
+        details: () => ({
+          name: 'Name is required',
+          channel: 'Select a channel',
+        }),
+      }
+      const { result } = renderHook(() =>
+        useWizard(FORM_STEPS, { validate })
+      )
+
+      let errors: Record<string, string> | null
+      act(() => { errors = result.current.next() })
+
+      expect(errors!).toEqual({
+        name: 'Name is required',
+        channel: 'Select a channel',
+      })
+      expect(result.current.currentStep).toBe('details')
+    })
+  })
 })

package/src/index.ts

@@ -22,12 +22,41 @@ export {
   getFilterDescription,
 } from './filter-encoding'
 export { useCRUDMutation } from './useCRUDMutation'
+export {
+  useMessages,
+  useMessage,
+  useCreateMessage,
+  useSendMessage,
+  useScheduleMessage,
+  useSendTestMessage,
+  useMessageChannels,
+} from './useMessages'
+export {
+  useMessageTemplates,
+  useMessageTemplate,
+  useCreateMessageTemplate,
+  useUpdateMessageTemplate,
+  useDeleteMessageTemplate,
+} from './useMessageTemplates'
 export { useSavedViews } from './useSavedViews'
 export type { SavedView as SavedViewEntry } from './useSavedViews'
 export { useRecentlyViewed } from './useRecentlyViewed'
 export { useWizard } from './useWizard'
-export type { WizardState } from './useWizard'
+export type { WizardState, WizardOptions } from './useWizard'
 export { useCSVImport, useCSVExport } from './useCSV'
+export { useEntityTable } from './useEntityTable'
+export type { UseEntityTableOptions, UseEntityTableReturn } from './useEntityTable'
+export { useTargetListDetail, useTargetListMutations, TARGET_LIST_KEYS } from './useTargetLists'
+export type { TargetListApiFns, UseTargetListMutationsOptions } from './useTargetLists'
+export { useEnrichment, useBatchEnrichment, useQueueStatus } from './useEnrichment'
+export type {
+  UseEnrichmentState,
+  UseEnrichmentOptions,
+  UseBatchEnrichmentState,
+  UseBatchEnrichmentOptions,
+  UseQueueStatusState,
+  UseQueueStatusOptions,
+} from './useEnrichment'
 export type {
   CSVColumnMapping,
   CSVPreviewResult,
@@ -35,3 +64,5 @@ export type {
   CSVImportStep,
   UseCSVImportState,
 } from './useCSV'
+export { useAsyncOptions } from './useAsyncOptions'
+export type { UseAsyncOptionsResult } from './useAsyncOptions'

package/src/useAsyncOptions.ts

@@ -0,0 +1,60 @@
+import { useState, useEffect, useCallback, useRef } from 'react'
+
+export interface UseAsyncOptionsResult<T> {
+  data: T[]
+  loading: boolean
+  error: Error | null
+  refresh: () => void
+}
+
+export function useAsyncOptions<T>(
+  fetcher: () => Promise<T[]>,
+  opts?: { enabled?: boolean; defaultValue?: T[] }
+): UseAsyncOptionsResult<T> {
+  const enabled = opts?.enabled ?? true
+  const defaultValue = opts?.defaultValue ?? []
+
+  const [data, setData] = useState<T[]>(defaultValue)
+  const [loading, setLoading] = useState(enabled)
+  const [error, setError] = useState<Error | null>(null)
+  const mountedRef = useRef(true)
+  const fetcherRef = useRef(fetcher)
+  fetcherRef.current = fetcher
+
+  const doFetch = useCallback(() => {
+    setLoading(true)
+    setError(null)
+
+    fetcherRef.current()
+      .then((result) => {
+        if (mountedRef.current) {
+          setData(result)
+        }
+      })
+      .catch((err: unknown) => {
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)))
+        }
+      })
+      .finally(() => {
+        if (mountedRef.current) {
+          setLoading(false)
+        }
+      })
+  }, [])
+
+  useEffect(() => {
+    mountedRef.current = true
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
+
+  useEffect(() => {
+    if (enabled) {
+      doFetch()
+    }
+  }, [enabled, doFetch])
+
+  return { data, loading, error, refresh: doFetch }
+}

package/src/useCSV.ts

@@ -1,19 +1,19 @@
 import { useState, useCallback } from 'react'
 
 export interface CSVColumnMapping {
-  csv_column: string
-  target_field: string
+  csvColumn: string
+  targetField: string
 }
 
 export interface CSVPreviewResult<TField extends string = string> {
   columns: string[]
-  sample_rows: Record<string, string>[]
-  suggested_mappings?: CSVColumnMapping[]
-  total_rows?: number
+  sampleRows: Record<string, string>[]
+  suggestedMappings?: CSVColumnMapping[]
+  totalRows?: number
 }
 
 export interface CSVImportResult {
-  total_rows: number
+  totalRows: number
   successful: number
   failed: number
   errors: Array<{ row: number; message: string }>
@@ -63,7 +63,7 @@ export function useCSVImport<TField extends string = string>({
       try {
         const previewData = await previewFn(selectedFile)
         setPreview(previewData)
-        setMappings(previewData.suggested_mappings ?? [])
+        setMappings(previewData.suggestedMappings ?? [])
         setStep('mapping')
       } catch {
         setError('Failed to preview CSV file')
@@ -76,13 +76,13 @@ export function useCSVImport<TField extends string = string>({
 
   const updateMapping = useCallback((csvColumn: string, targetField: string) => {
     setMappings((prev) => {
-      const existing = prev.find((m) => m.csv_column === csvColumn)
+      const existing = prev.find((m) => m.csvColumn === csvColumn)
       if (existing) {
         return prev.map((m) =>
-          m.csv_column === csvColumn ? { ...m, target_field: targetField } : m
+          m.csvColumn === csvColumn ? { ...m, targetField: targetField } : m
         )
       }
-      return [...prev, { csv_column: csvColumn, target_field: targetField }]
+      return [...prev, { csvColumn: csvColumn, targetField: targetField }]
     })
   }, [])
 

package/src/useEnrichment.ts

@@ -0,0 +1,156 @@
+import { useState, useCallback, useRef } from 'react'
+import type { EnrichmentResult, QueueStatus } from '@startsimpli/api'
+
+export interface EnrichFn {
+  (contactId: string): Promise<EnrichmentResult>
+}
+
+export interface BulkEnrichFn {
+  (contactIds: string[], onProgress?: (completed: number, total: number) => void): Promise<EnrichmentResult[]>
+}
+
+export interface QueueStatusFn {
+  (): Promise<QueueStatus>
+}
+
+export interface UseEnrichmentOptions {
+  enrichFn: EnrichFn
+  onSuccess?: (result: EnrichmentResult) => void
+}
+
+export interface UseEnrichmentState {
+  isEnriching: boolean
+  result: EnrichmentResult | null
+  error: string | null
+  enrich: (contactId: string) => Promise<void>
+  reset: () => void
+}
+
+export function useEnrichment({ enrichFn, onSuccess }: UseEnrichmentOptions): UseEnrichmentState {
+  const [isEnriching, setIsEnriching] = useState(false)
+  const [result, setResult] = useState<EnrichmentResult | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  const enrich = useCallback(
+    async (contactId: string) => {
+      setIsEnriching(true)
+      setError(null)
+      try {
+        const enrichResult = await enrichFn(contactId)
+        setResult(enrichResult)
+        onSuccess?.(enrichResult)
+      } catch (err: unknown) {
+        setError(err instanceof Error ? err.message : 'Enrichment failed')
+      } finally {
+        setIsEnriching(false)
+      }
+    },
+    [enrichFn, onSuccess]
+  )
+
+  const reset = useCallback(() => {
+    setResult(null)
+    setError(null)
+  }, [])
+
+  return { isEnriching, result, error, enrich, reset }
+}
+
+export interface UseBatchEnrichmentOptions {
+  bulkEnrichFn: BulkEnrichFn
+  onComplete?: (results: EnrichmentResult[]) => void
+}
+
+export interface UseBatchEnrichmentState {
+  isEnriching: boolean
+  progress: { completed: number; total: number }
+  results: EnrichmentResult[]
+  error: string | null
+  enrichBatch: (contactIds: string[]) => Promise<void>
+  cancel: () => void
+  reset: () => void
+}
+
+export function useBatchEnrichment({
+  bulkEnrichFn,
+  onComplete,
+}: UseBatchEnrichmentOptions): UseBatchEnrichmentState {
+  const [isEnriching, setIsEnriching] = useState(false)
+  const [progress, setProgress] = useState({ completed: 0, total: 0 })
+  const [results, setResults] = useState<EnrichmentResult[]>([])
+  const [error, setError] = useState<string | null>(null)
+  const cancelledRef = useRef(false)
+
+  const enrichBatch = useCallback(
+    async (contactIds: string[]) => {
+      cancelledRef.current = false
+      setIsEnriching(true)
+      setError(null)
+      setProgress({ completed: 0, total: contactIds.length })
+      setResults([])
+
+      try {
+        const batchResults = await bulkEnrichFn(contactIds, (completed, total) => {
+          if (!cancelledRef.current) {
+            setProgress({ completed, total })
+          }
+        })
+        if (!cancelledRef.current) {
+          setResults(batchResults)
+          onComplete?.(batchResults)
+        }
+      } catch (err: unknown) {
+        if (!cancelledRef.current) {
+          setError(err instanceof Error ? err.message : 'Batch enrichment failed')
+        }
+      } finally {
+        if (!cancelledRef.current) {
+          setIsEnriching(false)
+        }
+      }
+    },
+    [bulkEnrichFn, onComplete]
+  )
+
+  const cancel = useCallback(() => {
+    cancelledRef.current = true
+    setIsEnriching(false)
+  }, [])
+
+  const reset = useCallback(() => {
+    setResults([])
+    setError(null)
+    setProgress({ completed: 0, total: 0 })
+  }, [])
+
+  return { isEnriching, progress, results, error, enrichBatch, cancel, reset }
+}
+
+export interface UseQueueStatusOptions {
+  fetchQueueStatus: QueueStatusFn
+}
+
+export interface UseQueueStatusState {
+  queueStatus: QueueStatus | null
+  isLoading: boolean
+  refresh: () => Promise<void>
+}
+
+export function useQueueStatus({ fetchQueueStatus }: UseQueueStatusOptions): UseQueueStatusState {
+  const [queueStatus, setQueueStatus] = useState<QueueStatus | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+
+  const refresh = useCallback(async () => {
+    setIsLoading(true)
+    try {
+      const status = await fetchQueueStatus()
+      setQueueStatus(status)
+    } catch {
+      // Queue status may not be available
+    } finally {
+      setIsLoading(false)
+    }
+  }, [fetchQueueStatus])
+
+  return { queueStatus, isLoading, refresh }
+}