@startsimpli/hooks 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/hooks",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Shared React hooks for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -24,14 +24,19 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "@tanstack/react-query": ">=5.0.0"
+    "@tanstack/react-query": ">=5.0.0",
+    "@startsimpli/api": "workspace:*"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-query": {
       "optional": true
+    },
+    "@startsimpli/api": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@startsimpli/api": "workspace:*",
     "@tanstack/react-query": "^5.0.0",
     "@testing-library/react": "^14.0.0",
     "@types/node": "^20.11.0",

package/src/index.ts

@@ -22,12 +22,39 @@ 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 { useCSVImport, useCSVExport } from './useCSV'
+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,

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 }
+}

package/src/useMessageTemplates.ts

@@ -0,0 +1,67 @@
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import type { MessageTemplatesApi, MessageTemplateFilters, CreateMessageTemplateInput } from '@startsimpli/api'
+
+/**
+ * List message templates with optional filters (paginated)
+ */
+export function useMessageTemplates(api: MessageTemplatesApi, filters?: MessageTemplateFilters) {
+  return useQuery({
+    queryKey: ['messageTemplates', filters],
+    queryFn: () => api.list(filters),
+  })
+}
+
+/**
+ * Get a single message template by ID
+ */
+export function useMessageTemplate(api: MessageTemplatesApi, id: string) {
+  return useQuery({
+    queryKey: ['messageTemplates', id],
+    queryFn: () => api.get(id),
+    enabled: !!id,
+  })
+}
+
+/**
+ * Create a new message template
+ */
+export function useCreateMessageTemplate(api: MessageTemplatesApi) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (data: CreateMessageTemplateInput) => api.create(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messageTemplates'] })
+    },
+  })
+}
+
+/**
+ * Update an existing message template
+ */
+export function useUpdateMessageTemplate(api: MessageTemplatesApi) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Partial<CreateMessageTemplateInput> }) =>
+      api.update(id, data),
+    onSuccess: (_, variables) => {
+      queryClient.invalidateQueries({ queryKey: ['messageTemplates'] })
+      queryClient.invalidateQueries({ queryKey: ['messageTemplates', variables.id] })
+    },
+  })
+}
+
+/**
+ * Delete a message template
+ */
+export function useDeleteMessageTemplate(api: MessageTemplatesApi) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (id: string) => api.delete(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messageTemplates'] })
+    },
+  })
+}

package/src/useMessages.ts

@@ -0,0 +1,86 @@
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import type { MessagesApi, MessageFilters, CreateMessageInput, ScheduleMessageInput, SendTestInput } from '@startsimpli/api'
+
+/**
+ * List messages with optional filters (paginated)
+ */
+export function useMessages(api: MessagesApi, filters?: MessageFilters) {
+  return useQuery({
+    queryKey: ['messages', filters],
+    queryFn: () => api.list(filters),
+  })
+}
+
+/**
+ * Get a single message by ID
+ */
+export function useMessage(api: MessagesApi, id: string) {
+  return useQuery({
+    queryKey: ['messages', id],
+    queryFn: () => api.get(id),
+    enabled: !!id,
+  })
+}
+
+/**
+ * Create a new message (draft)
+ */
+export function useCreateMessage(api: MessagesApi) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (data: CreateMessageInput) => api.create(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messages'] })
+    },
+  })
+}
+
+/**
+ * Send a message immediately
+ */
+export function useSendMessage(api: MessagesApi, id: string) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: () => api.sendNow(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messages'] })
+      queryClient.invalidateQueries({ queryKey: ['messages', id] })
+    },
+  })
+}
+
+/**
+ * Schedule a message for future sending
+ */
+export function useScheduleMessage(api: MessagesApi, id: string) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (input: ScheduleMessageInput) => api.schedule(id, input),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['messages'] })
+      queryClient.invalidateQueries({ queryKey: ['messages', id] })
+    },
+  })
+}
+
+/**
+ * Send a test message
+ */
+export function useSendTestMessage(api: MessagesApi, id: string) {
+  return useMutation({
+    mutationFn: (input?: SendTestInput) => api.sendTest(id, input),
+  })
+}
+
+/**
+ * List available messaging channels
+ */
+export function useMessageChannels(api: MessagesApi) {
+  return useQuery({
+    queryKey: ['messages', 'channels'],
+    queryFn: () => api.getChannels(),
+  })
+}

package/src/useTargetLists.ts

@@ -0,0 +1,132 @@
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import type {
+  TargetList,
+  TargetListMember,
+  CreateTargetListInput,
+  UpdateTargetListInput,
+  TargetListFilters,
+  TargetListMemberFilters,
+  AddMembersResult,
+  RemoveMembersResult,
+  RefreshResult,
+  PaginatedResponse,
+} from '@startsimpli/api'
+
+export const TARGET_LIST_KEYS = {
+  all: ['target-lists'] as const,
+  lists: (filters?: TargetListFilters) => [...TARGET_LIST_KEYS.all, filters] as const,
+  detail: (id: string) => ['target-list', id] as const,
+  members: (listId: string, filters?: TargetListMemberFilters) =>
+    ['list-members', listId, filters] as const,
+}
+
+export interface TargetListApiFns {
+  list: (filters?: TargetListFilters) => Promise<PaginatedResponse<TargetList>>
+  get: (id: string) => Promise<TargetList>
+  create: (data: CreateTargetListInput) => Promise<TargetList>
+  update: (id: string, data: UpdateTargetListInput) => Promise<TargetList>
+  delete: (id: string) => Promise<void>
+  getMembers: (listId: string, filters?: TargetListMemberFilters) => Promise<PaginatedResponse<TargetListMember>>
+  addMembers: (listId: string, contactIds: string[]) => Promise<AddMembersResult>
+  removeMembers: (listId: string, contactIds: string[]) => Promise<RemoveMembersResult>
+  refresh: (listId: string) => Promise<RefreshResult>
+}
+
+export function useTargetListDetail(
+  id: string,
+  apiFns: Pick<TargetListApiFns, 'get'>
+) {
+  return useQuery({
+    queryKey: TARGET_LIST_KEYS.detail(id),
+    queryFn: () => apiFns.get(id),
+    enabled: !!id,
+  })
+}
+
+export interface UseTargetListMutationsOptions {
+  apiFns: Pick<TargetListApiFns, 'create' | 'update' | 'delete' | 'addMembers' | 'removeMembers' | 'refresh'>
+  onSuccess?: (action: string) => void
+  onError?: (action: string) => void
+}
+
+export function useTargetListMutations({
+  apiFns,
+  onSuccess,
+  onError,
+}: UseTargetListMutationsOptions) {
+  const queryClient = useQueryClient()
+
+  const invalidateList = (listId?: string) => {
+    queryClient.invalidateQueries({ queryKey: TARGET_LIST_KEYS.all })
+    if (listId) {
+      queryClient.invalidateQueries({ queryKey: TARGET_LIST_KEYS.detail(listId) })
+      queryClient.invalidateQueries({ queryKey: ['list-members', listId] })
+    }
+  }
+
+  const createList = useMutation({
+    mutationFn: (data: CreateTargetListInput) => apiFns.create(data),
+    onSuccess: () => {
+      invalidateList()
+      onSuccess?.('List created')
+    },
+    onError: () => onError?.('Failed to create list'),
+  })
+
+  const updateList = useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateTargetListInput }) =>
+      apiFns.update(id, data),
+    onSuccess: (_, variables) => {
+      invalidateList(variables.id)
+      onSuccess?.('List updated')
+    },
+    onError: () => onError?.('Failed to update list'),
+  })
+
+  const deleteList = useMutation({
+    mutationFn: (id: string) => apiFns.delete(id),
+    onSuccess: () => {
+      invalidateList()
+      onSuccess?.('List deleted')
+    },
+    onError: () => onError?.('Failed to delete list'),
+  })
+
+  const addMembersMutation = useMutation({
+    mutationFn: ({ listId, contactIds }: { listId: string; contactIds: string[] }) =>
+      apiFns.addMembers(listId, contactIds),
+    onSuccess: (_, variables) => {
+      invalidateList(variables.listId)
+      onSuccess?.('Members added')
+    },
+    onError: () => onError?.('Failed to add members'),
+  })
+
+  const removeMembersMutation = useMutation({
+    mutationFn: ({ listId, contactIds }: { listId: string; contactIds: string[] }) =>
+      apiFns.removeMembers(listId, contactIds),
+    onSuccess: (_, variables) => {
+      invalidateList(variables.listId)
+      onSuccess?.('Members removed')
+    },
+    onError: () => onError?.('Failed to remove members'),
+  })
+
+  const refreshList = useMutation({
+    mutationFn: (listId: string) => apiFns.refresh(listId),
+    onSuccess: (_, listId) => {
+      invalidateList(listId)
+      onSuccess?.('List refreshed')
+    },
+    onError: () => onError?.('Failed to refresh list'),
+  })
+
+  return {
+    createList,
+    updateList,
+    deleteList,
+    addMembers: addMembersMutation,
+    removeMembers: removeMembersMutation,
+    refreshList,
+  }
+}