@kelpie/ui 0.1.0

package/src/api/resources/agentTasks.ts

@@ -0,0 +1,172 @@
+import {
+  agentRunSchema,
+  agentTaskDefinitionSchema,
+  createRegisteredAgentBody,
+  registeredAgentBody,
+  registeredAgentSchema,
+  resolveAgentTaskBody,
+  resolvedAgentTaskSchema,
+  runAgentTaskBody,
+} from '@kelpie/schemas'
+import type {
+  AgentRun,
+  AgentRunStatus,
+  AgentTaskDefinition,
+  AgentTaskTargetType,
+  CreateRegisteredAgentInput,
+  RegisteredAgent,
+  RegisteredAgentInput,
+  ResolveAgentTaskInput,
+  ResolvedAgentTask,
+  RunAgentTaskInput,
+} from '@kelpie/schemas'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+
+import { ApiError } from '../client.ts'
+import { useApiClient } from '../context.ts'
+import { toError } from '../errors.ts'
+import { createReadOnlyResourceHooks, createResourceHooks } from '../resource.ts'
+import type {
+  ListOptions,
+  MutationResult,
+  RecordListResult,
+  RecordResult,
+  UpdateArguments,
+} from '../resource.ts'
+import { asMutationResult } from './mutation.ts'
+
+/**
+ * `/v1/agent-tasks`, `/v1/agent-runs` and `/v1/agents`: prompt recipes, their
+ * dispatch log, and the bring-your-own agents they dispatch to.
+ *
+ * Resolve and run are POSTs with a task id in the path, so both are written out
+ * the way `useCreateWebhook` is. A run settles on the server after the response
+ * returns, which is what `useAgentRun`'s polling is for.
+ */
+
+const tasks = createReadOnlyResourceHooks<AgentTaskDefinition>({
+  name: 'agent_tasks',
+  path: '/agent-tasks',
+  decode: agentTaskDefinitionSchema.parse,
+})
+
+/** The catalog for one target type. Code on the server, so never stale enough to refetch. */
+export function useAgentTasks(targetType: AgentTaskTargetType): RecordListResult<AgentTaskDefinition> {
+  return tasks.useList({ target_type: targetType })
+}
+
+/** The whole catalog, for labelling run-log rows by task id. */
+export function useAllAgentTasks(): RecordListResult<AgentTaskDefinition> {
+  return tasks.useList()
+}
+
+export interface ResolveAgentTaskArguments extends ResolveAgentTaskInput {
+  readonly taskId: string
+}
+
+/** A POST in verb only: it assembles a prompt and writes nothing, so no cache moves. */
+export function useResolveAgentTask(): MutationResult<ResolveAgentTaskArguments, ResolvedAgentTask> {
+  const client = useApiClient()
+  const mutation = useMutation({
+    mutationFn: ({ taskId, ...input }: ResolveAgentTaskArguments) =>
+      client.post(
+        `/agent-tasks/${taskId}/resolve`,
+        resolveAgentTaskBody(input),
+        resolvedAgentTaskSchema.parse,
+      ),
+  })
+
+  return asMutationResult(mutation)
+}
+
+export interface RunAgentTaskArguments extends RunAgentTaskInput {
+  readonly taskId: string
+}
+
+export function useRunAgentTask(): MutationResult<RunAgentTaskArguments, AgentRun> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: ({ taskId, ...input }: RunAgentTaskArguments) =>
+      client.post(`/agent-tasks/${taskId}/run`, runAgentTaskBody(input), agentRunSchema.parse),
+    onSettled: () => {
+      // The run log gained a row, and the agent's `last_run_at` moved with it.
+      void queryClient.invalidateQueries({ queryKey: ['agent_runs'] })
+      void queryClient.invalidateQueries({ queryKey: ['agents', 'list'] })
+    },
+  })
+
+  return asMutationResult(mutation)
+}
+
+const runs = createReadOnlyResourceHooks<AgentRun>({
+  name: 'agent_runs',
+  path: '/agent-runs',
+  decode: agentRunSchema.parse,
+})
+
+export interface AgentRunFilters {
+  readonly agentId?: string
+  readonly status?: AgentRunStatus
+}
+
+export function useAgentRuns(
+  filters: AgentRunFilters = {},
+  options: ListOptions = {},
+): RecordListResult<AgentRun> {
+  return runs.useList({ agent_id: filters.agentId, status: filters.status }, options)
+}
+
+const POLL_INTERVAL_MS = 750
+
+/**
+ * One run, polled while the dispatch is still moving. The server settles the
+ * run after the create response returns, so `queued` and `running` are moments
+ * the page would otherwise be stuck displaying forever.
+ */
+export function useAgentRun(id: string | undefined): RecordResult<AgentRun> {
+  const client = useApiClient()
+  const result = useQuery({
+    // The same key `runs.useRecord` would use, so the two never hold different
+    // copies of one run.
+    queryKey: ['agent_runs', 'detail', id ?? ''],
+    queryFn: () => client.get(`/agent-runs/${id ?? ''}`, agentRunSchema.parse),
+    enabled: id !== undefined,
+    refetchInterval: (query) => {
+      const status = query.state.data?.status
+
+      return status === 'queued' || status === 'running' ? POLL_INTERVAL_MS : false
+    },
+  })
+
+  return {
+    record: result.data,
+    isLoading: result.isPending && id !== undefined,
+    error: toError(result.error),
+    isNotFound: result.error instanceof ApiError && result.error.status === 404,
+  }
+}
+
+const agents = createResourceHooks<RegisteredAgent, CreateRegisteredAgentInput, RegisteredAgentInput>({
+  name: 'agents',
+  path: '/agents',
+  decode: registeredAgentSchema.parse,
+  createBody: createRegisteredAgentBody,
+  updateBody: registeredAgentBody,
+})
+
+export function useAgents(options: ListOptions = {}): RecordListResult<RegisteredAgent> {
+  return agents.useList({}, options)
+}
+
+export function useCreateAgent(): MutationResult<CreateRegisteredAgentInput, RegisteredAgent> {
+  return agents.useCreate()
+}
+
+export function useUpdateAgent(): MutationResult<UpdateArguments<RegisteredAgentInput>, RegisteredAgent> {
+  return agents.useUpdate()
+}
+
+export function useDeleteAgent(): MutationResult<string, void> {
+  return agents.useRemove()
+}

package/src/api/resources/candidates.ts

@@ -0,0 +1,69 @@
+import { candidateBody, candidateSchema, createCandidateBody } from '@kelpie/schemas'
+import type { Candidate, CandidateInput, CandidateStatus, CreateCandidateInput } from '@kelpie/schemas'
+
+import type { QueryParameters } from '../client.ts'
+import { createResourceHooks } from '../resource.ts'
+import type {
+  ListOptions,
+  MutationResult,
+  RecordListResult,
+  UpdateArguments,
+} from '../resource.ts'
+
+/**
+ * `/v1/candidates`, the Person↔Role link.
+ *
+ * There is no single-candidate hook. Every page that shows a candidacy already
+ * has the list it came from — a role's pipeline or a person's roles — so a
+ * detail fetch would be a second request for a record already on screen.
+ */
+
+const candidates = createResourceHooks<Candidate, CreateCandidateInput, CandidateInput>({
+  name: 'candidates',
+  path: '/candidates',
+  decode: candidateSchema.parse,
+  createBody: createCandidateBody,
+  updateBody: candidateBody,
+  // Every write files an activity on the candidate's person, and a delete takes
+  // the interview notes with it.
+  alsoInvalidates: ['activities', 'notes'],
+})
+
+/** The documented filters on `GET /v1/candidates`. */
+export interface CandidateFilters {
+  /** Candidacies on any of these roles. Repeats on the wire. */
+  readonly roleIds?: readonly string[]
+  /** Candidacies held by any of these people. Repeats on the wire. */
+  readonly personIds?: readonly string[]
+  /** Candidacies in any of these pipeline states. Repeats on the wire. */
+  readonly statuses?: readonly CandidateStatus[]
+  readonly limit?: number
+}
+
+function candidateQuery(filters: CandidateFilters): QueryParameters {
+  return {
+    role_id: filters.roleIds,
+    person_id: filters.personIds,
+    status: filters.statuses,
+    limit: filters.limit,
+  }
+}
+
+export function useCandidates(
+  filters: CandidateFilters = {},
+  options: ListOptions = {},
+): RecordListResult<Candidate> {
+  return candidates.useList(candidateQuery(filters), options)
+}
+
+export function useCreateCandidate(): MutationResult<CreateCandidateInput, Candidate> {
+  return candidates.useCreate()
+}
+
+export function useUpdateCandidate(): MutationResult<UpdateArguments<CandidateInput>, Candidate> {
+  return candidates.useUpdate()
+}
+
+export function useDeleteCandidate(): MutationResult<string, void> {
+  return candidates.useRemove()
+}

package/src/api/resources/companies.ts

@@ -0,0 +1,72 @@
+import { companyBody, companySchema } from '@kelpie/schemas'
+import type { Company, CompanyInput } from '@kelpie/schemas'
+
+import type { QueryParameters } from '../client.ts'
+import { createResourceHooks } from '../resource.ts'
+import type {
+  ListOptions,
+  MutationResult,
+  RecordListResult,
+  RecordResult,
+  UpdateArguments,
+} from '../resource.ts'
+
+/** `/v1/companies`. Create needs a name; the API defaults every other field. */
+
+export interface CreateCompanyInput extends CompanyInput {
+  readonly name: string
+}
+
+const companies = createResourceHooks<Company, CreateCompanyInput, CompanyInput>({
+  name: 'companies',
+  path: '/companies',
+  decode: companySchema.parse,
+  createBody: companyBody,
+  updateBody: companyBody,
+  // Every write here emits an activity server-side, in the same transaction, so
+  // a timeline rendered on this record is stale the moment the write lands.
+  alsoInvalidates: ['activities'],
+})
+
+/** The documented filters on `GET /v1/companies`. */
+export interface CompanyFilters {
+  /** Matches name, domain, industry, summary, account type, and tags. */
+  readonly term?: string
+  /** Companies where any of these people holds a position. Repeats on the wire. */
+  readonly personIds?: readonly string[]
+  readonly limit?: number
+  /** `field` ascending, `-field` descending. Only `name`, `created_at`, `updated_at` are sortable. */
+  readonly sort?: string
+}
+
+function companyQuery(filters: CompanyFilters): QueryParameters {
+  return {
+    q: filters.term,
+    person_id: filters.personIds,
+    limit: filters.limit,
+    sort: filters.sort,
+  }
+}
+
+export function useCompanies(
+  filters: CompanyFilters = {},
+  options: ListOptions = {},
+): RecordListResult<Company> {
+  return companies.useList(companyQuery(filters), options)
+}
+
+export function useCompany(id: string | undefined): RecordResult<Company> {
+  return companies.useRecord(id)
+}
+
+export function useCreateCompany(): MutationResult<CreateCompanyInput, Company> {
+  return companies.useCreate()
+}
+
+export function useUpdateCompany(): MutationResult<UpdateArguments<CompanyInput>, Company> {
+  return companies.useUpdate()
+}
+
+export function useDeleteCompany(): MutationResult<string, void> {
+  return companies.useRemove()
+}

package/src/api/resources/dashboard.ts

@@ -0,0 +1,39 @@
+import { dashboardSchema } from '@kelpie/schemas'
+import type { Dashboard } from '@kelpie/schemas'
+import { useQuery } from '@tanstack/react-query'
+
+import { useApiClient } from '../context.ts'
+import { toError } from '../errors.ts'
+
+/**
+ * `/v1/dashboard`, read-only: the workspace home in one request.
+ *
+ * Not a `createResourceHooks` resource. There is no collection, no id in a path,
+ * and no write, so the five verbs those hooks build would all be dead.
+ *
+ * Nothing invalidates this key from elsewhere. Every signal is derived from
+ * records other pages own, so listing the writes that could move a number here
+ * would mean naming most of the API. React Query refetches it on mount and on
+ * window focus, which is when a workspace home is looked at.
+ */
+
+const DASHBOARD_KEY = ['dashboard'] as const
+
+/** How many rows each embedded list carries. The totals beside them are exact regardless. */
+const SIGNAL_LIMIT = 5
+
+export interface DashboardState {
+  readonly dashboard: Dashboard | undefined
+  readonly isLoading: boolean
+  readonly error: Error | null
+}
+
+export function useDashboard(): DashboardState {
+  const client = useApiClient()
+  const result = useQuery({
+    queryKey: DASHBOARD_KEY,
+    queryFn: () => client.get('/dashboard', dashboardSchema.parse, { limit: SIGNAL_LIMIT }),
+  })
+
+  return { dashboard: result.data, isLoading: result.isPending, error: toError(result.error) }
+}

package/src/api/resources/deals.ts

@@ -0,0 +1,82 @@
+import { dealBody, dealSchema } from '@kelpie/schemas'
+import type { Deal, DealInput } from '@kelpie/schemas'
+
+import type { QueryParameters } from '../client.ts'
+import { createResourceHooks } from '../resource.ts'
+import type {
+  ListOptions,
+  MutationResult,
+  RecordListResult,
+  RecordResult,
+  UpdateArguments,
+} from '../resource.ts'
+
+/**
+ * `/v1/deals`. Create needs a name and a company; the API lands the deal in the
+ * pipeline's first open stage and hands it to the caller as owner.
+ */
+
+export interface CreateDealInput extends DealInput {
+  readonly name: string
+  readonly companyId: string
+}
+
+const deals = createResourceHooks<Deal, CreateDealInput, DealInput>({
+  name: 'deals',
+  path: '/deals',
+  decode: dealSchema.parse,
+  createBody: dealBody,
+  updateBody: dealBody,
+  // Every write here emits an activity server-side, in the same transaction, so
+  // a timeline rendered on this record is stale the moment the write lands.
+  alsoInvalidates: ['activities'],
+})
+
+/** The documented filters on `GET /v1/deals`. */
+export interface DealFilters {
+  /** Matches the deal's name, summary, tags, competitors, and its company's name. */
+  readonly term?: string
+  /** Deals at any of these companies. Repeats on the wire. */
+  readonly companyIds?: readonly string[]
+  /** Deals sitting in any of these stages. Repeats on the wire. */
+  readonly stageIds?: readonly string[]
+  /** Deals any of these people are on. Repeats on the wire. */
+  readonly personIds?: readonly string[]
+  readonly limit?: number
+  /** `field` ascending, `-field` descending. Only `name`, `created_at`, `updated_at` are sortable. */
+  readonly sort?: string
+}
+
+function dealQuery(filters: DealFilters): QueryParameters {
+  return {
+    q: filters.term,
+    company_id: filters.companyIds,
+    stage_id: filters.stageIds,
+    person_id: filters.personIds,
+    limit: filters.limit,
+    sort: filters.sort,
+  }
+}
+
+export function useDeals(
+  filters: DealFilters = {},
+  options: ListOptions = {},
+): RecordListResult<Deal> {
+  return deals.useList(dealQuery(filters), options)
+}
+
+export function useDeal(id: string | undefined): RecordResult<Deal> {
+  return deals.useRecord(id)
+}
+
+export function useCreateDeal(): MutationResult<CreateDealInput, Deal> {
+  return deals.useCreate()
+}
+
+export function useUpdateDeal(): MutationResult<UpdateArguments<DealInput>, Deal> {
+  return deals.useUpdate()
+}
+
+export function useDeleteDeal(): MutationResult<string, void> {
+  return deals.useRemove()
+}

package/src/api/resources/decisions.ts

@@ -0,0 +1,60 @@
+import { createDecisionBody, decisionBody, decisionSchema } from '@kelpie/schemas'
+import type {
+  CreateDecisionInput,
+  Decision,
+  DecisionInput,
+  RecordTargetType,
+} from '@kelpie/schemas'
+
+import type { QueryParameters } from '../client.ts'
+import { createResourceHooks } from '../resource.ts'
+import type { MutationResult, RecordListResult, UpdateArguments } from '../resource.ts'
+
+/**
+ * `/v1/decisions`, attachable to any CRM record.
+ *
+ * Unlike notes, the API answers a workspace-wide list too: `/decisions` is a
+ * page of its own, so the filters here are all optional.
+ *
+ * No `alsoInvalidates`: a decision write files no activity row and touches no
+ * other resource.
+ */
+
+const decisions = createResourceHooks<Decision, CreateDecisionInput, DecisionInput>({
+  name: 'decisions',
+  path: '/decisions',
+  decode: decisionSchema.parse,
+  createBody: createDecisionBody,
+  updateBody: decisionBody,
+})
+
+export interface DecisionFilters {
+  readonly targetType?: RecordTargetType
+  readonly targetId?: string
+  /** Matches the body, the rationale, the target type, and the target's name. */
+  readonly term?: string
+}
+
+function decisionQuery(filters: DecisionFilters): QueryParameters {
+  return {
+    target_type: filters.targetType,
+    target_id: filters.targetId,
+    q: filters.term,
+  }
+}
+
+export function useDecisions(filters: DecisionFilters = {}): RecordListResult<Decision> {
+  return decisions.useList(decisionQuery(filters))
+}
+
+export function useCreateDecision(): MutationResult<CreateDecisionInput, Decision> {
+  return decisions.useCreate()
+}
+
+export function useUpdateDecision(): MutationResult<UpdateArguments<DecisionInput>, Decision> {
+  return decisions.useUpdate()
+}
+
+export function useDeleteDecision(): MutationResult<string, void> {
+  return decisions.useRemove()
+}