@startsimpli/hooks 0.4.14 → 0.4.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/hooks",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "Shared React hooks for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -23,7 +23,7 @@
     "@tanstack/react-query": ">=5.0.0",
     "react": ">=18.0.0",
     "react-native": ">=0.74.0",
-    "@startsimpli/api": "0.5.19"
+    "@startsimpli/api": "0.5.22"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-query": {
@@ -46,7 +46,7 @@
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@startsimpli/api": "0.5.19"
+    "@startsimpli/api": "0.5.22"
   },
   "scripts": {
     "build": "tsup",

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__/useWorkflows.test.ts

@@ -0,0 +1,162 @@
+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 {
+  useWorkflows,
+  useWorkflow,
+  useWorkflowNodeTypes,
+  useCreateWorkflow,
+  useUpdateWorkflow,
+  useDeleteWorkflow,
+  useExecuteWorkflow,
+  useWorkflowExecution,
+  useWorkflowExecutions,
+  useCancelExecution,
+  useRetryExecution,
+  executionRefetchInterval,
+} from '../useWorkflows'
+import type { WorkflowsApi } 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<WorkflowsApi> = {}): WorkflowsApi {
+  return {
+    listWorkflows: vi.fn().mockResolvedValue({ results: [], count: 0 }),
+    getWorkflow: vi.fn().mockResolvedValue({ id: 'w1', name: 'Onboarding' }),
+    createWorkflow: vi.fn().mockResolvedValue({ id: 'w1' }),
+    updateWorkflow: vi.fn().mockResolvedValue({ id: 'w1', name: 'New' }),
+    deleteWorkflow: vi.fn().mockResolvedValue(undefined),
+    getNodeTypes: vi.fn().mockResolvedValue([{ slug: 'http', category: 'action', label: 'HTTP' }]),
+    executeWorkflow: vi.fn().mockResolvedValue({ executionId: 'e1', status: 'running' }),
+    getExecution: vi.fn().mockResolvedValue({ status: 'running', state: {}, nodeExecutions: [] }),
+    listExecutions: vi.fn().mockResolvedValue({ results: [], count: 0 }),
+    cancelExecution: vi.fn().mockResolvedValue({ id: 'e1', status: 'cancelled' }),
+    retryExecution: vi.fn().mockResolvedValue({ executionId: 'e2', status: 'pending' }),
+    ...overrides,
+  } as unknown as WorkflowsApi
+}
+
+describe('workflow query hooks', () => {
+  it('useWorkflows fetches the workflow list', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflows(api, { page: 1 }), { wrapper: wrap(mkClient()) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.listWorkflows).toHaveBeenCalledWith({ page: 1 })
+  })
+
+  it('useWorkflow fetches one workflow and is disabled without an id', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflow(api, ''), { wrapper: wrap(mkClient()) })
+    expect(result.current.fetchStatus).toBe('idle')
+    expect(api.getWorkflow).not.toHaveBeenCalled()
+  })
+
+  it('useWorkflowNodeTypes fetches the node-type registry', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflowNodeTypes(api), { wrapper: wrap(mkClient()) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.getNodeTypes).toHaveBeenCalled()
+  })
+
+  it('useWorkflowExecution fetches the execution detail and is disabled without an id', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflowExecution(api, ''), { wrapper: wrap(mkClient()) })
+    expect(result.current.fetchStatus).toBe('idle')
+    expect(api.getExecution).not.toHaveBeenCalled()
+  })
+
+  it('useWorkflowExecutions fetches executions for a workflow', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflowExecutions(api, 'w1', { page: 1 }), {
+      wrapper: wrap(mkClient()),
+    })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.listExecutions).toHaveBeenCalledWith('w1', { page: 1 })
+  })
+})
+
+describe('workflow mutation hooks invalidate the right queries', () => {
+  it('useCreateWorkflow invalidates the workflows list', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useCreateWorkflow(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ name: 'Onboarding' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'list']]))
+  })
+
+  it('useUpdateWorkflow invalidates the workflow detail', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useUpdateWorkflow(fakeApi(), 'w1'), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ name: 'New' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'detail', 'w1']]))
+  })
+
+  it('useDeleteWorkflow invalidates the workflows list', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useDeleteWorkflow(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate('w1') })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'list']]))
+  })
+
+  it('useExecuteWorkflow surfaces the executionId', async () => {
+    const qc = mkClient()
+    const api = fakeApi()
+    const { result } = renderHook(() => useExecuteWorkflow(api, 'w1'), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ foo: 'bar' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.executeWorkflow).toHaveBeenCalledWith('w1', { foo: 'bar' })
+    expect(result.current.data?.executionId).toBe('e1')
+  })
+
+  it('useCancelExecution invalidates the execution query key', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useCancelExecution(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate('e1') })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'execution', 'e1']]))
+  })
+
+  it('useRetryExecution invalidates the execution query key', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useRetryExecution(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate('e1') })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'execution', 'e1']]))
+  })
+})
+
+describe('executionRefetchInterval', () => {
+  it('polls while running/pending/waiting and stops when terminal', () => {
+    expect(executionRefetchInterval('running')).toBeGreaterThan(0)
+    expect(executionRefetchInterval('pending')).toBeGreaterThan(0)
+    expect(executionRefetchInterval('waiting')).toBeGreaterThan(0)
+    expect(executionRefetchInterval('completed')).toBe(false)
+    expect(executionRefetchInterval('failed')).toBe(false)
+    expect(executionRefetchInterval('cancelled')).toBe(false)
+    expect(executionRefetchInterval(undefined)).toBe(false)
+  })
+})

package/src/index.ts

@@ -86,3 +86,5 @@ export {
   useDeleteAccessKey,
   useAuditLog,
 } from './useVault'
+export * from './usePresentations'
+export * from './useWorkflows'

package/src/usePresentations.ts

@@ -0,0 +1,120 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import type {
+  PresentationsApi,
+  DeckInput,
+  DeckListParams,
+  DeckStatus,
+  GenerateDeckInput,
+  RegenerateSlideInput,
+  SlideInput,
+} from '@startsimpli/api'
+
+/** TanStack Query hooks over PresentationsApi (epic startsim-3ks).
+ *
+ * Each hook takes the PresentationsApi instance (e.g. `api.presentations`),
+ * matching the useVault / useMessages convention. Generation + compile are
+ * async on the backend, so the deck detail and the lightweight status query
+ * are invalidated together and the status query self-polls while in flight.
+ */
+
+const DECKS_KEY = ['presentations', 'decks'] as const
+const deckKey = (id: string) => ['presentations', 'deck', id]
+const deckStatusKey = (id: string) => ['presentations', 'deck-status', id]
+
+const POLL_MS = 1500
+
+/** Refetch interval for the status query: poll while work is in flight. */
+export function deckStatusRefetchInterval(status: DeckStatus | undefined): number | false {
+  return status === 'generating' || status === 'draft' ? POLL_MS : false
+}
+
+function invalidateDeck(qc: ReturnType<typeof useQueryClient>, id: string) {
+  qc.invalidateQueries({ queryKey: deckKey(id) })
+  qc.invalidateQueries({ queryKey: deckStatusKey(id) })
+  qc.invalidateQueries({ queryKey: DECKS_KEY })
+}
+
+// --- Decks ---
+export function useDecks(api: PresentationsApi, params?: DeckListParams) {
+  return useQuery({
+    queryKey: ['presentations', 'decks', params],
+    queryFn: () => api.listDecks(params),
+  })
+}
+
+export function useDeck(api: PresentationsApi, id: string) {
+  return useQuery({
+    queryKey: deckKey(id),
+    queryFn: () => api.getDeck(id),
+    enabled: !!id,
+  })
+}
+
+/** Self-polling per-slide generation status; stops when ready/error. */
+export function useDeckStatus(api: PresentationsApi, id: string, enabled = true) {
+  return useQuery({
+    queryKey: deckStatusKey(id),
+    queryFn: () => api.getDeckStatus(id),
+    enabled: enabled && !!id,
+    refetchInterval: (query) => deckStatusRefetchInterval(query.state.data?.status),
+  })
+}
+
+export function useCreateDeck(api: PresentationsApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: DeckInput) => api.createDeck(data),
+    onSuccess: () => qc.invalidateQueries({ queryKey: DECKS_KEY }),
+  })
+}
+
+export function useUpdateDeck(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: Partial<DeckInput>) => api.updateDeck(id, data),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}
+
+export function useDeleteDeck(api: PresentationsApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => api.deleteDeck(id),
+    onSuccess: () => qc.invalidateQueries({ queryKey: DECKS_KEY }),
+  })
+}
+
+// --- Generation pipeline ---
+export function useGenerateDeck(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data?: GenerateDeckInput) => api.generateDeck(id, data),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}
+
+export function useRegenerateSlide(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({ slideNumber, ...data }: { slideNumber: number } & RegenerateSlideInput) =>
+      api.regenerateSlide(id, slideNumber, data),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}
+
+export function useUpdateSlide(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({ slideNumber, ...data }: { slideNumber: number } & SlideInput) =>
+      api.updateSlide(id, slideNumber, data),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}
+
+export function useCompileDeck(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: () => api.compileDeck(id),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}

package/src/useWorkflows.ts

@@ -0,0 +1,122 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import type {
+  WorkflowsApi,
+  WorkflowInput,
+  WorkflowListParams,
+  ExecutionListParams,
+  RunStatus,
+} from '@startsimpli/api'
+
+/** TanStack Query hooks over WorkflowsApi (epic startsim-xsh.12).
+ *
+ * Each hook takes the WorkflowsApi instance (e.g. `api.workflows`), matching
+ * the usePresentations / useVault convention. Executions are async on the
+ * backend, so the execution detail query self-polls while a run is in flight
+ * and stops on a terminal status.
+ */
+
+const WORKFLOWS_KEY = ['workflows', 'list'] as const
+const workflowKey = (id: string) => ['workflows', 'detail', id]
+const executionKey = (executionId: string) => ['workflows', 'execution', executionId]
+const executionsKey = (workflowId: string) => ['workflows', 'executions', workflowId]
+
+const POLL_MS = 1000
+
+/** Refetch interval for the execution detail query: poll while a run is live. */
+export function executionRefetchInterval(status: RunStatus | undefined): number | false {
+  return status === 'running' || status === 'pending' || status === 'waiting' ? POLL_MS : false
+}
+
+// --- Workflows ---
+export function useWorkflows(api: WorkflowsApi, params?: WorkflowListParams) {
+  return useQuery({
+    queryKey: ['workflows', 'list', params],
+    queryFn: () => api.listWorkflows(params),
+  })
+}
+
+export function useWorkflow(api: WorkflowsApi, id: string) {
+  return useQuery({
+    queryKey: workflowKey(id),
+    queryFn: () => api.getWorkflow(id),
+    enabled: !!id,
+  })
+}
+
+export function useWorkflowNodeTypes(api: WorkflowsApi) {
+  return useQuery({
+    queryKey: ['workflows', 'node-types'],
+    queryFn: () => api.getNodeTypes(),
+  })
+}
+
+export function useCreateWorkflow(api: WorkflowsApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: WorkflowInput) => api.createWorkflow(data),
+    onSuccess: () => qc.invalidateQueries({ queryKey: WORKFLOWS_KEY }),
+  })
+}
+
+export function useUpdateWorkflow(api: WorkflowsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: Partial<WorkflowInput>) => api.updateWorkflow(id, data),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: workflowKey(id) })
+      qc.invalidateQueries({ queryKey: WORKFLOWS_KEY })
+    },
+  })
+}
+
+export function useDeleteWorkflow(api: WorkflowsApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => api.deleteWorkflow(id),
+    onSuccess: () => qc.invalidateQueries({ queryKey: WORKFLOWS_KEY }),
+  })
+}
+
+// --- Execution ---
+/** Kick off a run; the mutation result surfaces the executionId. */
+export function useExecuteWorkflow(api: WorkflowsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (contextData?: Record<string, unknown>) => api.executeWorkflow(id, contextData),
+    onSuccess: () => qc.invalidateQueries({ queryKey: executionsKey(id) }),
+  })
+}
+
+/** Self-polling execution detail; stops when the run reaches a terminal state. */
+export function useWorkflowExecution(api: WorkflowsApi, executionId: string, enabled = true) {
+  return useQuery({
+    queryKey: executionKey(executionId),
+    queryFn: () => api.getExecution(executionId),
+    enabled: enabled && !!executionId,
+    refetchInterval: (query) => executionRefetchInterval(query.state.data?.status),
+  })
+}
+
+export function useWorkflowExecutions(api: WorkflowsApi, workflowId: string, params?: ExecutionListParams) {
+  return useQuery({
+    queryKey: ['workflows', 'executions', workflowId, params],
+    queryFn: () => api.listExecutions(workflowId, params),
+    enabled: !!workflowId,
+  })
+}
+
+export function useCancelExecution(api: WorkflowsApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (executionId: string) => api.cancelExecution(executionId),
+    onSuccess: (_data, executionId) => qc.invalidateQueries({ queryKey: executionKey(executionId) }),
+  })
+}
+
+export function useRetryExecution(api: WorkflowsApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (executionId: string) => api.retryExecution(executionId),
+    onSuccess: (_data, executionId) => qc.invalidateQueries({ queryKey: executionKey(executionId) }),
+  })
+}