@startsimpli/hooks 0.4.11 → 0.4.15

package/README.md

@@ -0,0 +1,225 @@
+# @startsimpli/hooks
+
+Shared React hooks for every StartSimpli app. This is where dashboard plumbing lives — entity tables with CSV export, paginated table filters, saved views, recently-viewed, wizards, TanStack Query wrappers over `@startsimpli/api` (messages, target lists, vault), enrichment state machines, and small a11y/lifecycle helpers (`useReducedMotion`, `useRefetchOnFocus`). Reach for this package whenever you're building a list/detail/edit screen, a multi-step form, or anything that talks to the Django backend through `@startsimpli/api`.
+
+Consumed today by `raise-simpli/web-app`, `market-simpli`, `vault-web`, and the React Native preview in `examples/mobile-rn`. Web-only hooks have `.native.ts` siblings so React Native bundlers resolve a safe stub (or platform-appropriate implementation) automatically.
+
+## Install
+
+Workspace dep — in the app's `package.json`:
+```json
+{ "dependencies": { "@startsimpli/hooks": "workspace:*" } }
+```
+Add `transpilePackages: ['@startsimpli/hooks']` to `next.config.ts` (Next apps only). Peer deps are `react`, `@tanstack/react-query` (for any hook that talks to the API), and `@startsimpli/api` (for the typed-API hooks); all are marked optional so a leaf app that only wants `useReducedMotion` doesn't have to install the world.
+
+## Public surface
+
+### Data + mutations (TanStack Query over `@startsimpli/api`)
+
+| Export | Signature | Consumed by |
+|---|---|---|
+| `useCRUDMutation` | `(mutationFn, { invalidateKeys, onSuccess?, onError? }) => UseMutationResult` — generic mutation that invalidates a list of query keys on success. | available; no app consumers yet |
+| `useMessages` | `(api: MessagesApi, filters?) => UseQueryResult<PaginatedResponse<Message>>` — paginated message list. | market-simpli, raise-simpli |
+| `useMessage` | `(api, id) => UseQueryResult<Message>` — single message detail. | market-simpli |
+| `useCreateMessage` / `useSendMessage` / `useScheduleMessage` / `useSendTestMessage` | message lifecycle mutations; invalidate the `messages` cache. | market-simpli |
+| `useMessageChannels` | `(api) => UseQueryResult<Channel[]>` — available send channels. | market-simpli |
+| `useMessageTemplates` / `useMessageTemplate` / `useCreateMessageTemplate` / `useUpdateMessageTemplate` / `useDeleteMessageTemplate` | template CRUD over `MessageTemplatesApi`. | market-simpli |
+| `useTargetListDetail` | `(id, { get }) => UseQueryResult<TargetList>` — fetch one list. | market-simpli |
+| `useTargetListMutations` | `({ apiFns, onSuccess?, onError? }) => { createList, updateList, deleteList, addMembers, removeMembers, refreshList }` — bundled list/member mutations with shared invalidation. | market-simpli |
+| `TARGET_LIST_KEYS` | query-key factory `{ all, lists(filters), detail(id), members(listId, filters) }`. | market-simpli |
+
+### Vault (`startsim-d30.3.2`) — over `VaultApi`
+
+| Export | Signature | Consumed by |
+|---|---|---|
+| `useEnvironments` / `useEnvironment` | list and detail queries for vault environments. | vault-web |
+| `useCreateEnvironment` / `useUpdateEnvironment` / `useDeleteEnvironment` | environment mutations; invalidate the environments cache. | vault-web |
+| `useSecrets` / `useCreateSecret` / `useUpdateSecret` / `useDeleteSecret` | per-environment secret CRUD; also refresh the env detail/list so `secret_count` stays accurate. | vault-web |
+| `useRevealSecret` | on-demand mutation — values are never auto-fetched. | vault-web |
+| `useAccessKeys` / `useCreateAccessKey` / `useDeleteAccessKey` | access-key CRUD per environment. | vault-web |
+| `useAuditLog` | paginated audit log for an environment. | vault-web |
+
+### Tables, filters, saved views
+
+| Export | Signature | Consumed by |
+|---|---|---|
+| `useEntityTable<T>` | `({ items, idField?, csvFilename, csvColumns, csvRowMapper }) => { selectedItem, editingItem, viewMode, showCreateForm, exportIdsRef, exportCSV, isExporting, openView, openEdit, openCreate, closePanel }` — list/detail/edit + CSV export state for an entity grid. | market-simpli (prospects, organizations, deals, lists, …) |
+| `useTableFilters<TFilters>` | `(initial) => { filters, setFilter, setPage, setPageSize, setSearch, setSort, resetFilters }` — generic paginated table filter state; mutating a filter resets `page` to 1. | market-simpli (wrapped as `useMarketTableFilters`) |
+| `useSavedViews<T>` | `({ resource, loadFn, saveFn, updateFn, deleteFn }) => { views, currentViewId, loading, error, saveView, updateView, deleteView, loadView, getCurrentView, refreshViews }` — persisted named filter views. | market-simpli (`SavedViewsMenu`) |
+| `useRecentlyViewed<T>` | `(storageKey, maxItems=5) => { items, timestamps, trackView, clear }` — localStorage-backed recents list. | raise-simpli (`RecentlyViewedSidebar`) |
+
+### URL-encoded filter state (pure functions, no React)
+
+| Export | Purpose |
+|---|---|
+| `encodeFilterConfig` / `decodeFilterConfig` | URL-safe base64 (de)serializer for a `FilterConfig`. |
+| `parseUrlFilters` | `URLSearchParams -> EncodedFilterState`. |
+| `createSimpleFilter` / `mergeFilters` | helpers for constructing/combining filter graphs. |
+| `getFilterDescription` | human-readable summary for a saved filter chip. |
+| `FilterOperator`, `FilterValue`, `FilterCondition`, `FilterGroup`, `FilterConfig`, `EncodedFilterState`, `FilterValidationError`, `FilterValidationResult` | types. |
+
+Used by `raise-simpli/web-app/src/lib/filtering/parser.ts` (which re-exports them for backwards-compat).
+
+### Wizards + forms
+
+| Export | Signature | Consumed by |
+|---|---|---|
+| `useWizard<TStep>` | `(steps, initialStep?, opts?)` or `(steps, opts?)` → `{ currentStep, stepIndex, totalSteps, isFirstStep, isLastStep, canGoBack, canGoNext, errors, goTo, next, prev, reset, clearErrors }` — typed step machine with per-step validators. | market-simpli (`CampaignForm`) |
+| `useAsyncOptions<T>` | `(fetcher, { enabled?, defaultValue? }?) => { data, loading, error, refresh }` — load select options from an async source. | market-simpli (`CampaignForm`) |
+
+### CSV import / export
+
+| Export | Signature | Consumed by |
+|---|---|---|
+| `useCSVImport<TField>` | `({ previewFn, importFn, onSuccess? }) => UseCSVImportState` — platform-neutral upload → preview → mapping → import state machine; safe on web and React Native. | market-simpli (`ImportCSV`) |
+| `useCSVExport` | `({ exportFn, filename? }) => { exportCSV, isExporting }` — web-only download via Blob + anchor; React Native resolves a stub that throws. | market-simpli (also driven by `useEntityTable`) |
+
+### Enrichment
+
+| Export | Purpose | Consumed by |
+|---|---|---|
+| `useEnrichment` | single-contact enrichment state. | market-simpli (settings/enrichment page) |
+| `useBatchEnrichment` | batched enrichment with progress + cancel. | market-simpli |
+| `useQueueStatus` | poll the enrichment queue depth. | market-simpli |
+
+### Lifecycle + a11y
+
+| Export | Signature | Consumed by |
+|---|---|---|
+| `useReducedMotion` | `() => boolean` — tracks `(prefers-reduced-motion: reduce)`. | raise-simpli (`toast-notification`, `InvestorCard`, `PipelineColumn`), `examples/mobile-rn` |
+| `useRefetchOnFocus` | `(refetch, pathname, enabled=true) => void` — re-runs `refetch` on tab-focus and route change, skipping initial mount, debounced 2s. | raise-simpli (dashboard, messages, fundraises, calendar, outreach pages) |
+
+## Usage
+
+### Entity table + CSV export (market-simpli)
+
+```tsx
+// market-simpli/src/modules/prospects/components/ProspectsTable.tsx
+import { useEntityTable } from '@startsimpli/hooks'
+
+const {
+  selectedItem, editingItem, viewMode, showCreateForm,
+  openView, openEdit, openCreate, closePanel,
+} = useEntityTable<Prospect>({
+  items: data?.results || [],
+  idField: 'internalId',
+  csvFilename: 'prospects',
+  csvColumns: ['Name', 'Email', 'Phone', 'Company', 'Stage', 'Lead Score', 'Created'],
+  csvRowMapper: (p) => [
+    p.name || '',
+    p.email || '',
+    p.phone || '',
+    p.companyName || '',
+    p.stage || '',
+    p.leadScore?.toString() || '',
+    new Date(p.createdAt).toLocaleDateString(),
+  ],
+})
+```
+
+### Vault environments (vault-web)
+
+```tsx
+// vault-web/src/app/(dashboard)/environments/page.tsx
+import {
+  useCreateEnvironment,
+  useDeleteEnvironment,
+  useEnvironments,
+  useUpdateEnvironment,
+} from '@startsimpli/hooks'
+import { api } from '@/lib/api'
+
+const { data, isLoading, isError } = useEnvironments(api.vault)
+const createEnv = useCreateEnvironment(api.vault)
+const updateEnv = useUpdateEnvironment(api.vault)
+const deleteEnv = useDeleteEnvironment(api.vault)
+```
+
+Secret CRUD takes the env slug once and returns mutations scoped to it; deleting/creating a secret automatically refreshes the env detail + the environments list so `secret_count` stays accurate:
+
+```tsx
+// vault-web/src/app/(dashboard)/environments/[slug]/page.tsx
+import {
+  useCreateSecret,
+  useDeleteSecret,
+  useRevealSecret,
+  useSecrets,
+  useUpdateSecret,
+} from '@startsimpli/hooks'
+
+const { data, isLoading } = useSecrets(api.vault, slug)
+const createSecret = useCreateSecret(api.vault, slug)
+const updateSecret = useUpdateSecret(api.vault, slug)
+const deleteSecret = useDeleteSecret(api.vault, slug)
+const reveal = useRevealSecret(api.vault, slug)
+```
+
+### Wizard with per-step validation (market-simpli)
+
+```tsx
+// market-simpli/src/modules/campaigns/components/CampaignForm.tsx
+import { useWizard } from '@startsimpli/hooks'
+
+const STEPS = ['details', 'sender', 'sequence'] as const
+type CampaignStep = (typeof STEPS)[number]
+
+const wizard = useWizard<CampaignStep>(STEPS, {
+  validate: {
+    details: () => {
+      const errs: Record<string, string> = {}
+      if (!formDataRef.current.name.trim()) errs.name = 'Campaign name is required'
+      if (!formDataRef.current.channel) errs.channel = 'Please select a messaging channel'
+      return Object.keys(errs).length ? errs : null
+    },
+    sequence: () => {
+      const errs: Record<string, string> = {}
+      if (formDataRef.current.sequence.length === 0) {
+        errs.sequence = 'Please add at least one step to the campaign sequence'
+      }
+      return Object.keys(errs).length ? errs : null
+    },
+  },
+})
+```
+
+### Refetch on tab focus / route change (raise-simpli)
+
+```tsx
+// raise-simpli/web-app/src/app/(dashboard)/messages/page.tsx
+import { useRefetchOnFocus } from '@startsimpli/hooks'
+import { usePathname } from 'next/navigation'
+
+useRefetchOnFocus(fetchMessages, usePathname() ?? '')
+```
+
+### Saved views (market-simpli)
+
+```tsx
+// market-simpli/src/shared/components/SavedViewsMenu.tsx
+import { useSavedViews } from '@startsimpli/hooks'
+
+const {
+  views, currentViewId, loading,
+  saveView: saveNewView, deleteView: removeView, loadView,
+} = useSavedViews<MarketSavedView>({
+  resource,
+  loadFn: loadViews,
+  saveFn: saveView,
+  updateFn: updateView,
+  deleteFn: deleteView,
+})
+```
+
+## Verification
+
+```bash
+cd packages/hooks
+pnpm vitest run
+pnpm tsc --noEmit
+```
+
+10 test files, 83 tests passing (`useAsyncOptions`, `useCRUDMutation`, `useEntityTable`, `useRecentlyViewed`, `useReducedMotion`, `useRefetchOnFocus`, `useSavedViews`, `useTableFilters`, `useVault`, `useWizard`).
+
+## Shared-first
+
+See monorepo CLAUDE.md rule 9: hooks live here, not in any app's `src/`. If a hook is used by one app today but plausibly useful to another (a paginated table filter, a CSV importer, a saved-view menu, a wizard, a TanStack Query wrapper over `@startsimpli/api`), write it in this package from day one. Don't wrap a shared hook in an app-local context just to add a field — extend the shared signature.

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@startsimpli/hooks",
-  "version": "0.4.11",
+  "version": "0.4.15",
   "description": "Shared React hooks for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./src/index.ts",
+      "react-native": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "src",
@@ -14,18 +19,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "type-check": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
-    "@startsimpli/api": "workspace:*",
     "@tanstack/react-query": ">=5.0.0",
-    "react": ">=18.0.0"
+    "react": ">=18.0.0",
+    "react-native": ">=0.74.0",
+    "@startsimpli/api": "0.5.22"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-query": {
@@ -33,10 +31,12 @@
     },
     "@startsimpli/api": {
       "optional": true
+    },
+    "react-native": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@startsimpli/api": "workspace:*",
     "@tanstack/react-query": "^5.99.2",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^20.19.39",
@@ -45,6 +45,15 @@
     "react-dom": "^19.2.5",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.5",
+    "@startsimpli/api": "0.5.22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
   }
-}
+}

package/src/__tests__/usePresentations.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import React from 'react'
+import {
+  useDecks,
+  useDeck,
+  useCreateDeck,
+  useGenerateDeck,
+  useRegenerateSlide,
+  useCompileDeck,
+  deckStatusRefetchInterval,
+} from '../usePresentations'
+import type { PresentationsApi } from '@startsimpli/api'
+
+function mkClient() {
+  return new QueryClient({
+    defaultOptions: { mutations: { retry: false }, queries: { retry: false } },
+  })
+}
+function wrap(qc: QueryClient) {
+  return ({ children }: { children: React.ReactNode }) =>
+    React.createElement(QueryClientProvider, { client: qc }, children)
+}
+function trackInvalidations(qc: QueryClient): unknown[][] {
+  const calls: unknown[][] = []
+  const orig = qc.invalidateQueries.bind(qc)
+  qc.invalidateQueries = ((arg: { queryKey: unknown[] }) => {
+    calls.push(arg.queryKey)
+    return orig(arg)
+  }) as typeof qc.invalidateQueries
+  return calls
+}
+function fakeApi(overrides: Partial<PresentationsApi> = {}): PresentationsApi {
+  return {
+    listDecks: vi.fn().mockResolvedValue({ results: [], count: 0 }),
+    getDeck: vi.fn().mockResolvedValue({ id: 'd1', title: 'Pitch' }),
+    createDeck: vi.fn().mockResolvedValue({ id: 'd1' }),
+    generateDeck: vi.fn().mockResolvedValue({ id: 'd1', status: 'generating' }),
+    regenerateSlide: vi.fn().mockResolvedValue({ id: 's2', slideNumber: 2 }),
+    compileDeck: vi.fn().mockResolvedValue({ status: 'ready', pptxUrl: 'p', pdfUrl: 'q' }),
+    getDeckStatus: vi.fn().mockResolvedValue({ status: 'generating', slides: [] }),
+    ...overrides,
+  } as unknown as PresentationsApi
+}
+
+describe('presentation query hooks', () => {
+  it('useDecks fetches the deck list', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useDecks(api, { page: 1 }), { wrapper: wrap(mkClient()) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.listDecks).toHaveBeenCalledWith({ page: 1 })
+  })
+
+  it('useDeck fetches one deck and is disabled without an id', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useDeck(api, ''), { wrapper: wrap(mkClient()) })
+    // disabled — never fetches
+    expect(result.current.fetchStatus).toBe('idle')
+    expect(api.getDeck).not.toHaveBeenCalled()
+  })
+})
+
+describe('presentation mutation hooks invalidate the right queries', () => {
+  it('useCreateDeck invalidates the decks list', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useCreateDeck(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ title: 'Pitch' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['presentations', 'decks']]))
+  })
+
+  it('useGenerateDeck invalidates the deck detail + status', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useGenerateDeck(fakeApi(), 'd1'), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ outline: 'Slide 1' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(
+      expect.arrayContaining([
+        ['presentations', 'deck', 'd1'],
+        ['presentations', 'deck-status', 'd1'],
+      ])
+    )
+  })
+
+  it('useRegenerateSlide invalidates the deck detail + status', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useRegenerateSlide(fakeApi(), 'd1'), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ slideNumber: 2, instruction: 'punchier' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(
+      expect.arrayContaining([
+        ['presentations', 'deck', 'd1'],
+        ['presentations', 'deck-status', 'd1'],
+      ])
+    )
+  })
+
+  it('useCompileDeck invalidates the deck detail', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useCompileDeck(fakeApi(), 'd1'), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate() })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['presentations', 'deck', 'd1']]))
+  })
+})
+
+describe('deckStatusRefetchInterval', () => {
+  it('polls while generating/draft and stops when ready/error', () => {
+    expect(deckStatusRefetchInterval('generating')).toBeGreaterThan(0)
+    expect(deckStatusRefetchInterval('draft')).toBeGreaterThan(0)
+    expect(deckStatusRefetchInterval('ready')).toBe(false)
+    expect(deckStatusRefetchInterval('error')).toBe(false)
+    expect(deckStatusRefetchInterval(undefined)).toBe(false)
+  })
+})

package/src/__tests__/useVault.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import React from 'react'
+import { useCreateSecret, useDeleteSecret, useUpdateSecret } from '../useVault'
+import type { VaultApi } from '@startsimpli/api'
+
+/** startsim-drl: secret mutations must invalidate the env LIST (carries
+ * secret_count) and env DETAIL too, not only the secrets list — otherwise
+ * the /environments page sticks on a stale count.
+ */
+
+function mkClient() {
+  const qc = new QueryClient({
+    defaultOptions: { mutations: { retry: false }, queries: { retry: false } },
+  })
+  return qc
+}
+
+function wrap(qc: QueryClient) {
+  return ({ children }: { children: React.ReactNode }) =>
+    React.createElement(QueryClientProvider, { client: qc }, children)
+}
+
+function trackInvalidations(qc: QueryClient): unknown[][] {
+  const calls: unknown[][] = []
+  const orig = qc.invalidateQueries.bind(qc)
+  qc.invalidateQueries = ((arg: { queryKey: unknown[] }) => {
+    calls.push(arg.queryKey)
+    return orig(arg)
+  }) as typeof qc.invalidateQueries
+  return calls
+}
+
+function fakeApi(overrides: Partial<VaultApi> = {}): VaultApi {
+  return {
+    createSecret: vi.fn().mockResolvedValue({ id: 'sec-1' }),
+    updateSecret: vi.fn().mockResolvedValue({ id: 'sec-1' }),
+    deleteSecret: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  } as unknown as VaultApi
+}
+
+describe('secret mutations also invalidate environment queries (startsim-drl)', () => {
+  it('useCreateSecret invalidates secrets + environments + environment(slug)', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useCreateSecret(fakeApi(), 'quinns-mac'), {
+      wrapper: wrap(qc),
+    })
+
+    await act(async () => {
+      result.current.mutate({ key: 'K', value: 'v' })
+    })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+
+    expect(seen).toEqual(
+      expect.arrayContaining([
+        ['vault', 'secrets', 'quinns-mac'],
+        ['vault', 'environments'],
+        ['vault', 'environment', 'quinns-mac'],
+      ]),
+    )
+  })
+
+  it('useUpdateSecret invalidates the same three keys', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useUpdateSecret(fakeApi(), 'quinns-mac'), {
+      wrapper: wrap(qc),
+    })
+
+    await act(async () => {
+      result.current.mutate({ id: 'sec-1', data: { value: 'v2' } })
+    })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+
+    expect(seen).toEqual(
+      expect.arrayContaining([
+        ['vault', 'secrets', 'quinns-mac'],
+        ['vault', 'environments'],
+        ['vault', 'environment', 'quinns-mac'],
+      ]),
+    )
+  })
+
+  it('useDeleteSecret invalidates the same three keys', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useDeleteSecret(fakeApi(), 'quinns-mac'), {
+      wrapper: wrap(qc),
+    })
+
+    await act(async () => {
+      result.current.mutate('sec-1')
+    })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+
+    expect(seen).toEqual(
+      expect.arrayContaining([
+        ['vault', 'secrets', 'quinns-mac'],
+        ['vault', 'environments'],
+        ['vault', 'environment', 'quinns-mac'],
+      ]),
+    )
+  })
+})