@startsimpli/hooks 0.4.9 → 0.4.14

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.9",
+  "version": "0.4.14",
   "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.19"
   },
   "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.19"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
   }
-}
+}

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'],
+      ]),
+    )
+  })
+})

package/src/index.ts

@@ -68,3 +68,21 @@ export type {
 } from './useCSV'
 export { useAsyncOptions } from './useAsyncOptions'
 export type { UseAsyncOptionsResult } from './useAsyncOptions'
+
+// Vault — environments, secrets, access keys, audit (startsim-d30.3.2)
+export {
+  useEnvironments,
+  useEnvironment,
+  useCreateEnvironment,
+  useUpdateEnvironment,
+  useDeleteEnvironment,
+  useSecrets,
+  useCreateSecret,
+  useUpdateSecret,
+  useDeleteSecret,
+  useRevealSecret,
+  useAccessKeys,
+  useCreateAccessKey,
+  useDeleteAccessKey,
+  useAuditLog,
+} from './useVault'

package/src/useCSV-core.ts

@@ -0,0 +1,144 @@
+import { useState, useCallback } from 'react'
+
+export interface CSVColumnMapping {
+  csvColumn: string
+  targetField: string
+}
+
+export interface CSVPreviewResult<TField extends string = string> {
+  columns: string[]
+  sampleRows: Record<string, string>[]
+  suggestedMappings?: CSVColumnMapping[]
+  totalRows?: number
+}
+
+export interface CSVImportResult {
+  totalRows: number
+  successful: number
+  failed: number
+  errors: Array<{ row: number; message: string }>
+}
+
+export type CSVImportStep = 'upload' | 'mapping' | 'importing' | 'complete'
+
+export interface UseCSVImportOptions<TField extends string = string> {
+  previewFn: (file: File) => Promise<CSVPreviewResult<TField>>
+  importFn: (file: File, mappings: CSVColumnMapping[]) => Promise<CSVImportResult>
+  onSuccess?: (result: CSVImportResult) => void
+}
+
+export interface UseCSVImportState {
+  step: CSVImportStep
+  file: File | null
+  preview: CSVPreviewResult | null
+  mappings: CSVColumnMapping[]
+  result: CSVImportResult | null
+  isLoading: boolean
+  error: string | null
+  handleFileSelect: (file: File) => Promise<void>
+  updateMapping: (csvColumn: string, targetField: string) => void
+  startImport: () => Promise<void>
+  reset: () => void
+  goBack: () => void
+}
+
+/**
+ * Platform-neutral CSV import state machine.
+ *
+ * The actual file reading is delegated to the caller-provided previewFn/importFn,
+ * so this hook never touches the DOM — `File` is used only as a type. It is safe
+ * on web and React Native alike, which is why it lives in the shared core rather
+ * than the platform-specific useCSV entries.
+ */
+export function useCSVImport<TField extends string = string>({
+  previewFn,
+  importFn,
+  onSuccess,
+}: UseCSVImportOptions<TField>): UseCSVImportState {
+  const [step, setStep] = useState<CSVImportStep>('upload')
+  const [file, setFile] = useState<File | null>(null)
+  const [preview, setPreview] = useState<CSVPreviewResult | null>(null)
+  const [mappings, setMappings] = useState<CSVColumnMapping[]>([])
+  const [result, setResult] = useState<CSVImportResult | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const handleFileSelect = useCallback(
+    async (selectedFile: File) => {
+      setFile(selectedFile)
+      setError(null)
+      setIsLoading(true)
+      try {
+        const previewData = await previewFn(selectedFile)
+        setPreview(previewData)
+        setMappings(previewData.suggestedMappings ?? [])
+        setStep('mapping')
+      } catch {
+        setError('Failed to preview CSV file')
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [previewFn]
+  )
+
+  const updateMapping = useCallback((csvColumn: string, targetField: string) => {
+    setMappings((prev) => {
+      const existing = prev.find((m) => m.csvColumn === csvColumn)
+      if (existing) {
+        return prev.map((m) =>
+          m.csvColumn === csvColumn ? { ...m, targetField: targetField } : m
+        )
+      }
+      return [...prev, { csvColumn: csvColumn, targetField: targetField }]
+    })
+  }, [])
+
+  const startImport = useCallback(async () => {
+    if (!file) return
+    setStep('importing')
+    setError(null)
+    try {
+      const importResult = await importFn(file, mappings)
+      setResult(importResult)
+      setStep('complete')
+      onSuccess?.(importResult)
+    } catch {
+      setError('Failed to import CSV')
+      setStep('mapping')
+    }
+  }, [file, mappings, importFn, onSuccess])
+
+  const reset = useCallback(() => {
+    setStep('upload')
+    setFile(null)
+    setPreview(null)
+    setMappings([])
+    setResult(null)
+    setError(null)
+  }, [])
+
+  const goBack = useCallback(() => {
+    if (step === 'mapping') setStep('upload')
+  }, [step])
+
+  return {
+    step,
+    file,
+    preview,
+    mappings,
+    result,
+    isLoading,
+    error,
+    handleFileSelect,
+    updateMapping,
+    startImport,
+    reset,
+    goBack,
+  }
+}
+
+export interface UseCSVExportOptions {
+  exportFn: () => Promise<Blob | string>
+  filename?: string
+}

package/src/useCSV.native.ts

@@ -0,0 +1,26 @@
+import { useState, useCallback } from 'react'
+import type { UseCSVExportOptions } from './useCSV-core'
+
+// Types + the platform-neutral useCSVImport state machine live in the core.
+export * from './useCSV-core'
+
+/**
+ * useCSVExport — React Native stub.
+ *
+ * The web version triggers a browser file download (Blob + anchor click), which
+ * has no direct React Native equivalent. Rather than silently no-op, exportCSV
+ * fails loud so callers wire up a native save/share flow (expo-file-system +
+ * expo-sharing) explicitly. Metro resolves this file over useCSV.ts on native.
+ */
+export function useCSVExport({ exportFn: _exportFn, filename: _filename }: UseCSVExportOptions) {
+  const [isExporting] = useState(false)
+
+  const exportCSV = useCallback(async () => {
+    throw new Error(
+      'useCSVExport: browser-download export is web-only. On React Native, ' +
+        'save the CSV with expo-file-system and share it via expo-sharing.'
+    )
+  }, [])
+
+  return { exportCSV, isExporting }
+}

package/src/useCSV.ts

@@ -1,140 +1,16 @@
 import { useState, useCallback } from 'react'
-
-export interface CSVColumnMapping {
-  csvColumn: string
-  targetField: string
-}
-
-export interface CSVPreviewResult<TField extends string = string> {
-  columns: string[]
-  sampleRows: Record<string, string>[]
-  suggestedMappings?: CSVColumnMapping[]
-  totalRows?: number
-}
-
-export interface CSVImportResult {
-  totalRows: number
-  successful: number
-  failed: number
-  errors: Array<{ row: number; message: string }>
-}
-
-export type CSVImportStep = 'upload' | 'mapping' | 'importing' | 'complete'
-
-export interface UseCSVImportOptions<TField extends string = string> {
-  previewFn: (file: File) => Promise<CSVPreviewResult<TField>>
-  importFn: (file: File, mappings: CSVColumnMapping[]) => Promise<CSVImportResult>
-  onSuccess?: (result: CSVImportResult) => void
-}
-
-export interface UseCSVImportState {
-  step: CSVImportStep
-  file: File | null
-  preview: CSVPreviewResult | null
-  mappings: CSVColumnMapping[]
-  result: CSVImportResult | null
-  isLoading: boolean
-  error: string | null
-  handleFileSelect: (file: File) => Promise<void>
-  updateMapping: (csvColumn: string, targetField: string) => void
-  startImport: () => Promise<void>
-  reset: () => void
-  goBack: () => void
-}
-
-export function useCSVImport<TField extends string = string>({
-  previewFn,
-  importFn,
-  onSuccess,
-}: UseCSVImportOptions<TField>): UseCSVImportState {
-  const [step, setStep] = useState<CSVImportStep>('upload')
-  const [file, setFile] = useState<File | null>(null)
-  const [preview, setPreview] = useState<CSVPreviewResult | null>(null)
-  const [mappings, setMappings] = useState<CSVColumnMapping[]>([])
-  const [result, setResult] = useState<CSVImportResult | null>(null)
-  const [isLoading, setIsLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-
-  const handleFileSelect = useCallback(
-    async (selectedFile: File) => {
-      setFile(selectedFile)
-      setError(null)
-      setIsLoading(true)
-      try {
-        const previewData = await previewFn(selectedFile)
-        setPreview(previewData)
-        setMappings(previewData.suggestedMappings ?? [])
-        setStep('mapping')
-      } catch {
-        setError('Failed to preview CSV file')
-      } finally {
-        setIsLoading(false)
-      }
-    },
-    [previewFn]
-  )
-
-  const updateMapping = useCallback((csvColumn: string, targetField: string) => {
-    setMappings((prev) => {
-      const existing = prev.find((m) => m.csvColumn === csvColumn)
-      if (existing) {
-        return prev.map((m) =>
-          m.csvColumn === csvColumn ? { ...m, targetField: targetField } : m
-        )
-      }
-      return [...prev, { csvColumn: csvColumn, targetField: targetField }]
-    })
-  }, [])
-
-  const startImport = useCallback(async () => {
-    if (!file) return
-    setStep('importing')
-    setError(null)
-    try {
-      const importResult = await importFn(file, mappings)
-      setResult(importResult)
-      setStep('complete')
-      onSuccess?.(importResult)
-    } catch {
-      setError('Failed to import CSV')
-      setStep('mapping')
-    }
-  }, [file, mappings, importFn, onSuccess])
-
-  const reset = useCallback(() => {
-    setStep('upload')
-    setFile(null)
-    setPreview(null)
-    setMappings([])
-    setResult(null)
-    setError(null)
-  }, [])
-
-  const goBack = useCallback(() => {
-    if (step === 'mapping') setStep('upload')
-  }, [step])
-
-  return {
-    step,
-    file,
-    preview,
-    mappings,
-    result,
-    isLoading,
-    error,
-    handleFileSelect,
-    updateMapping,
-    startImport,
-    reset,
-    goBack,
-  }
-}
-
-export interface UseCSVExportOptions {
-  exportFn: () => Promise<Blob | string>
-  filename?: string
-}
-
+import type { UseCSVExportOptions } from './useCSV-core'
+
+// Types + the platform-neutral useCSVImport state machine live in the core.
+export * from './useCSV-core'
+
+/**
+ * useCSVExport — web implementation.
+ *
+ * Builds a Blob and triggers a browser download via an anchor click. This is
+ * inherently DOM-bound; React Native resolves useCSV.native.ts instead (which
+ * throws, since downloading a file has no direct RN equivalent).
+ */
 export function useCSVExport({ exportFn, filename = 'export.csv' }: UseCSVExportOptions) {
   const [isExporting, setIsExporting] = useState(false)
 

package/src/useRecentlyViewed.native.ts

@@ -0,0 +1,56 @@
+import { useState, useCallback, useEffect } from 'react'
+
+interface StoredItem<T> {
+  item: T
+  viewedAt: number
+}
+
+/**
+ * useRecentlyViewed — React Native implementation.
+ *
+ * Web persists to localStorage. React Native has no synchronous storage, so this
+ * keeps an in-memory store keyed by storageKey at module scope — which mirrors
+ * localStorage's app-wide sharing within a session but does NOT survive an app
+ * restart. Persistence across launches needs an async backend (AsyncStorage);
+ * tracked as a follow-up (startsim-sw1.5 notes). Metro resolves this file over
+ * useRecentlyViewed.ts on native builds.
+ */
+const memoryStore = new Map<string, StoredItem<unknown>[]>()
+
+export function useRecentlyViewed<T extends { id: string }>(
+  storageKey: string,
+  maxItems: number = 5
+) {
+  const [items, setItems] = useState<StoredItem<T>[]>(
+    () => (memoryStore.get(storageKey) as StoredItem<T>[]) ?? []
+  )
+
+  // Re-sync if the key changes.
+  useEffect(() => {
+    setItems((memoryStore.get(storageKey) as StoredItem<T>[]) ?? [])
+  }, [storageKey])
+
+  const trackView = useCallback(
+    (item: T) => {
+      setItems((prev) => {
+        const deduped = prev.filter((entry) => entry.item.id !== item.id)
+        const updated = [{ item, viewedAt: Date.now() }, ...deduped].slice(0, maxItems)
+        memoryStore.set(storageKey, updated as StoredItem<unknown>[])
+        return updated
+      })
+    },
+    [maxItems, storageKey]
+  )
+
+  const clear = useCallback(() => {
+    setItems([])
+    memoryStore.delete(storageKey)
+  }, [storageKey])
+
+  return {
+    items: items.map((entry) => entry.item),
+    timestamps: items.map((entry) => ({ id: entry.item.id, viewedAt: entry.viewedAt })),
+    trackView,
+    clear,
+  }
+}

package/src/useReducedMotion.native.ts

@@ -0,0 +1,34 @@
+/**
+ * useReducedMotion — React Native implementation.
+ *
+ * Web uses window.matchMedia('(prefers-reduced-motion: reduce)'); React Native
+ * exposes the same preference through AccessibilityInfo. Metro resolves this
+ * file over useReducedMotion.ts on native builds.
+ */
+
+import { useEffect, useState } from 'react'
+import { AccessibilityInfo } from 'react-native'
+
+export function useReducedMotion(): boolean {
+  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false)
+
+  useEffect(() => {
+    let active = true
+
+    AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {
+      if (active) setPrefersReducedMotion(enabled)
+    })
+
+    const subscription = AccessibilityInfo.addEventListener(
+      'reduceMotionChanged',
+      (enabled) => setPrefersReducedMotion(enabled)
+    )
+
+    return () => {
+      active = false
+      subscription.remove()
+    }
+  }, [])
+
+  return prefersReducedMotion
+}

package/src/useRefetchOnFocus.native.ts

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from 'react'
+import { AppState } from 'react-native'
+
+/**
+ * useRefetchOnFocus — React Native implementation.
+ *
+ * Web listens for document 'visibilitychange'; React Native has no document, so
+ * this watches AppState for the app returning to the foreground ('active'). The
+ * pathname-change behaviour and 2s debounce are identical to the web version.
+ * Metro resolves this file over useRefetchOnFocus.ts on native builds.
+ */
+export function useRefetchOnFocus(
+  refetch: () => void,
+  pathname: string,
+  enabled = true
+): void {
+  const mounted = useRef(false)
+  const lastRefetch = useRef(0)
+
+  useEffect(() => {
+    if (!enabled) return
+
+    if (!mounted.current) {
+      mounted.current = true
+      return
+    }
+
+    const now = Date.now()
+    if (now - lastRefetch.current < 2000) return
+
+    lastRefetch.current = now
+    refetch()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathname, enabled])
+
+  useEffect(() => {
+    if (!enabled) return
+
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active' && mounted.current) {
+        const now = Date.now()
+        if (now - lastRefetch.current < 2000) return
+        lastRefetch.current = now
+        refetch()
+      }
+    })
+
+    return () => subscription.remove()
+  }, [refetch, enabled])
+}

package/src/useVault.ts

@@ -0,0 +1,142 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import type {
+  VaultAccessKeyInput,
+  VaultApi,
+  VaultEnvironmentInput,
+  VaultListParams,
+  VaultSecretInput,
+} from '@startsimpli/api'
+
+/** TanStack Query hooks over VaultApi (startsim-d30.3.2).
+ *
+ * Each hook takes the VaultApi instance (e.g. `api.vault`), matching the
+ * useMessages convention. Secrets are revealed on demand (a mutation), never
+ * auto-fetched, so values are only pulled when the user asks.
+ */
+
+const ENVIRONMENTS_KEY = ['vault', 'environments'] as const
+const environmentKey = (slug: string) => ['vault', 'environment', slug]
+const secretsKey = (slug: string) => ['vault', 'secrets', slug]
+const accessKeysKey = (slug: string) => ['vault', 'access-keys', slug]
+
+/** Secret mutations alter the env's `secret_count`, so refresh the list +
+ * detail too — otherwise the /environments page shows a stale count
+ * (startsim-drl). */
+function invalidateSecretQueries(qc: ReturnType<typeof useQueryClient>, slug: string) {
+  qc.invalidateQueries({ queryKey: secretsKey(slug) })
+  qc.invalidateQueries({ queryKey: ENVIRONMENTS_KEY })
+  qc.invalidateQueries({ queryKey: environmentKey(slug) })
+}
+
+// --- Environments ---
+export function useEnvironments(api: VaultApi, params?: VaultListParams) {
+  return useQuery({
+    queryKey: ['vault', 'environments', params],
+    queryFn: () => api.listEnvironments(params),
+  })
+}
+
+export function useEnvironment(api: VaultApi, slug: string) {
+  return useQuery({
+    queryKey: ['vault', 'environment', slug],
+    queryFn: () => api.getEnvironment(slug),
+    enabled: !!slug,
+  })
+}
+
+export function useCreateEnvironment(api: VaultApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: VaultEnvironmentInput) => api.createEnvironment(data),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ENVIRONMENTS_KEY }),
+  })
+}
+
+export function useUpdateEnvironment(api: VaultApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({ slug, data }: { slug: string; data: Partial<VaultEnvironmentInput> }) =>
+      api.updateEnvironment(slug, data),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ENVIRONMENTS_KEY }),
+  })
+}
+
+export function useDeleteEnvironment(api: VaultApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (slug: string) => api.deleteEnvironment(slug),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ENVIRONMENTS_KEY }),
+  })
+}
+
+// --- Secrets ---
+export function useSecrets(api: VaultApi, slug: string, params?: VaultListParams) {
+  return useQuery({
+    queryKey: ['vault', 'secrets', slug, params],
+    queryFn: () => api.listSecrets(slug, params),
+    enabled: !!slug,
+  })
+}
+
+export function useCreateSecret(api: VaultApi, slug: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: VaultSecretInput) => api.createSecret(slug, data),
+    onSuccess: () => invalidateSecretQueries(qc, slug),
+  })
+}
+
+export function useUpdateSecret(api: VaultApi, slug: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Partial<VaultSecretInput> }) =>
+      api.updateSecret(slug, id, data),
+    onSuccess: () => invalidateSecretQueries(qc, slug),
+  })
+}
+
+export function useDeleteSecret(api: VaultApi, slug: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => api.deleteSecret(slug, id),
+    onSuccess: () => invalidateSecretQueries(qc, slug),
+  })
+}
+
+export function useRevealSecret(api: VaultApi, slug: string) {
+  return useMutation({ mutationFn: (id: string) => api.revealSecret(slug, id) })
+}
+
+// --- Access keys ---
+export function useAccessKeys(api: VaultApi, slug: string, params?: VaultListParams) {
+  return useQuery({
+    queryKey: ['vault', 'access-keys', slug, params],
+    queryFn: () => api.listAccessKeys(slug, params),
+    enabled: !!slug,
+  })
+}
+
+export function useCreateAccessKey(api: VaultApi, slug: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: VaultAccessKeyInput) => api.createAccessKey(slug, data),
+    onSuccess: () => qc.invalidateQueries({ queryKey: accessKeysKey(slug) }),
+  })
+}
+
+export function useDeleteAccessKey(api: VaultApi, slug: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => api.deleteAccessKey(slug, id),
+    onSuccess: () => qc.invalidateQueries({ queryKey: accessKeysKey(slug) }),
+  })
+}
+
+// --- Audit ---
+export function useAuditLog(api: VaultApi, slug: string, params?: VaultListParams) {
+  return useQuery({
+    queryKey: ['vault', 'audit', slug, params],
+    queryFn: () => api.listAudit(slug, params),
+    enabled: !!slug,
+  })
+}