@kelpie/ui 0.1.0

package/src/api/resources/planItems.ts

@@ -0,0 +1,103 @@
+import { createPlanItemBody, planItemBody, planItemSchema } from '@kelpie/schemas'
+import type {
+  CreatePlanItemInput,
+  PipelineKind,
+  PlanItem,
+  PlanItemInput,
+  PlanItemStatus,
+} from '@kelpie/schemas'
+
+import type { QueryParameters } from '../client.ts'
+import { createResourceHooks } from '../resource.ts'
+import type { ListOptions, MutationResult, RecordListResult, UpdateArguments } from '../resource.ts'
+
+/**
+ * `/v1/plan_items`: the dated next steps on the four pipelines.
+ *
+ * Unlike notes, this list is answerable workspace-wide, because the Planning
+ * page is exactly that question. `useRecordPlanItems` narrows it to one record's
+ * panel and `usePlanItemsForRecords` to a page of them.
+ *
+ * No `alsoInvalidates`: a plan item write emits no activity and touches no other
+ * resource. The one cross-resource effect runs the other way, when deleting a
+ * pipeline record takes its plan items with it.
+ */
+
+const planItems = createResourceHooks<PlanItem, CreatePlanItemInput, PlanItemInput>({
+  name: 'planItems',
+  path: '/plan_items',
+  decode: planItemSchema.parse,
+  createBody: createPlanItemBody,
+  updateBody: planItemBody,
+})
+
+/** The `?limit=` ceiling from `api.md`. A caller asking for a bounded set may ask for all of it. */
+export const MAX_PAGE_SIZE = 200
+
+export interface PlanItemFilters {
+  readonly targetType?: PipelineKind
+  /** The records to read steps for. Repeats on the wire: `?target_id=a&target_id=b`. */
+  readonly targetIds?: readonly string[]
+  readonly statuses?: readonly PlanItemStatus[]
+  /** Inclusive `YYYY-MM-DD` bounds. The calendar asks for one month with the pair. */
+  readonly from?: string
+  readonly to?: string
+  /** Page size. Worth setting only when the filter already bounds the answer. */
+  readonly limit?: number
+}
+
+function planItemQuery(filters: PlanItemFilters): QueryParameters {
+  return {
+    target_type: filters.targetType,
+    target_id: filters.targetIds,
+    status: filters.statuses,
+    from: filters.from,
+    to: filters.to,
+    limit: filters.limit,
+  }
+}
+
+export function usePlanItems(
+  filters: PlanItemFilters = {},
+  options: ListOptions = {},
+): RecordListResult<PlanItem> {
+  return planItems.useList(planItemQuery(filters), options)
+}
+
+/** One record's plan, in date order: what the panel on a detail page shows. */
+export function useRecordPlanItems(
+  targetType: PipelineKind,
+  targetId: string,
+): RecordListResult<PlanItem> {
+  return usePlanItems({ targetType, targetIds: [targetId] })
+}
+
+/**
+ * The plan across a set of records: a Person's or a Company's roll-up.
+ *
+ * Held back until the ids are known. A list filtered by a set of ids has nothing
+ * to ask before then, and asking with the filter omitted would answer with the
+ * whole workspace instead of nothing. Ids past the `?target_id=` ceiling are
+ * dropped rather than sent, because the request would be a 422 in full.
+ */
+export function usePlanItemsForRecords(
+  targetType: PipelineKind,
+  targetIds: readonly string[],
+): RecordListResult<PlanItem> {
+  return usePlanItems(
+    { targetType, targetIds: targetIds.slice(0, MAX_PAGE_SIZE), limit: MAX_PAGE_SIZE },
+    { enabled: targetIds.length > 0 },
+  )
+}
+
+export function useCreatePlanItem(): MutationResult<CreatePlanItemInput, PlanItem> {
+  return planItems.useCreate()
+}
+
+export function useUpdatePlanItem(): MutationResult<UpdateArguments<PlanItemInput>, PlanItem> {
+  return planItems.useUpdate()
+}
+
+export function useDeletePlanItem(): MutationResult<string, void> {
+  return planItems.useRemove()
+}

package/src/api/resources/positions.ts

@@ -0,0 +1,70 @@
+import { createPositionBody, positionSchema, updatePositionBody } from '@kelpie/schemas'
+import type { CreatePositionInput, Position } from '@kelpie/schemas'
+
+import type { QueryParameters } from '../client.ts'
+import { createResourceHooks } from '../resource.ts'
+import type {
+  ListOptions,
+  MutationResult,
+  RecordListResult,
+  UpdateArguments,
+} from '../resource.ts'
+
+/**
+ * `/v1/positions`, the Person↔Company link holding the job title.
+ *
+ * Only the title is updatable. Re-pointing a link at a different person or
+ * company is a delete and a create, which is what the API accepts.
+ */
+
+export interface PositionTitleUpdate {
+  readonly title: string
+}
+
+const positions = createResourceHooks<Position, CreatePositionInput, PositionTitleUpdate>({
+  name: 'positions',
+  path: '/positions',
+  decode: positionSchema.parse,
+  createBody: createPositionBody,
+  updateBody: (input) => updatePositionBody(input.title),
+  // `?company_id=` on people and `?person_id=` on companies are lists this join
+  // decides the membership of. Without this, linking a person to a company shows
+  // the new row with the name still unfetched.
+  // Creating one also emits a `linked` activity on both the person and the
+  // company, so both timelines are stale too.
+  alsoInvalidates: ['people', 'companies', 'activities'],
+})
+
+export interface PositionFilters {
+  /** Positions held by any of these people. Repeats on the wire. */
+  readonly personIds?: readonly string[]
+  /** Positions held at any of these companies. Repeats on the wire. */
+  readonly companyIds?: readonly string[]
+  readonly limit?: number
+}
+
+function positionQuery(filters: PositionFilters): QueryParameters {
+  return { person_id: filters.personIds, company_id: filters.companyIds, limit: filters.limit }
+}
+
+export function usePositions(
+  filters: PositionFilters = {},
+  options: ListOptions = {},
+): RecordListResult<Position> {
+  return positions.useList(positionQuery(filters), options)
+}
+
+export function useCreatePosition(): MutationResult<CreatePositionInput, Position> {
+  return positions.useCreate()
+}
+
+export function useUpdatePositionTitle(): MutationResult<
+  UpdateArguments<PositionTitleUpdate>,
+  Position
+> {
+  return positions.useUpdate()
+}
+
+export function useDeletePosition(): MutationResult<string, void> {
+  return positions.useRemove()
+}

package/src/api/resources/raises.ts

@@ -0,0 +1,82 @@
+import { raiseBody, raiseSchema } from '@kelpie/schemas'
+import type { Raise, RaiseInput } 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/raises`. Create needs a name and a firm; the API lands the raise in the
+ * pipeline's first open stage and hands it to the caller as owner.
+ */
+
+export interface CreateRaiseInput extends RaiseInput {
+  readonly name: string
+  readonly companyId: string
+}
+
+const raises = createResourceHooks<Raise, CreateRaiseInput, RaiseInput>({
+  name: 'raises',
+  path: '/raises',
+  decode: raiseSchema.parse,
+  createBody: raiseBody,
+  updateBody: raiseBody,
+  // 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/raises`. */
+export interface RaiseFilters {
+  /** Matches the raise's name, summary, tags, and its firm's name. */
+  readonly term?: string
+  /** Raises with any of these firms. Repeats on the wire. */
+  readonly companyIds?: readonly string[]
+  /** Raises sitting in any of these stages. Repeats on the wire. */
+  readonly stageIds?: readonly string[]
+  /** Raises any of these people are key 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 raiseQuery(filters: RaiseFilters): 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 useRaises(
+  filters: RaiseFilters = {},
+  options: ListOptions = {},
+): RecordListResult<Raise> {
+  return raises.useList(raiseQuery(filters), options)
+}
+
+export function useRaise(id: string | undefined): RecordResult<Raise> {
+  return raises.useRecord(id)
+}
+
+export function useCreateRaise(): MutationResult<CreateRaiseInput, Raise> {
+  return raises.useCreate()
+}
+
+export function useUpdateRaise(): MutationResult<UpdateArguments<RaiseInput>, Raise> {
+  return raises.useUpdate()
+}
+
+export function useDeleteRaise(): MutationResult<string, void> {
+  return raises.useRemove()
+}

package/src/api/resources/roles.ts

@@ -0,0 +1,65 @@
+import { roleBody, roleSchema } from '@kelpie/schemas'
+import type { Role, RoleInput, RoleStatus } 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/roles`. Create needs a title; the API opens the role. */
+
+export interface CreateRoleInput extends RoleInput {
+  readonly title: string
+}
+
+const roles = createResourceHooks<Role, CreateRoleInput, RoleInput>({
+  name: 'roles',
+  path: '/roles',
+  decode: roleSchema.parse,
+  createBody: roleBody,
+  updateBody: roleBody,
+  // Deleting a role takes its candidacies with it, and each one files an unlink
+  // on a person's timeline, so both caches are stale the moment a role goes.
+  alsoInvalidates: ['candidates', 'activities'],
+})
+
+/** The documented filters on `GET /v1/roles`. */
+export interface RoleFilters {
+  /** Matches the role's title, which is what the mockup's filter box matches. */
+  readonly term?: string
+  /** Roles in any of these statuses. Repeats on the wire. */
+  readonly statuses?: readonly RoleStatus[]
+  readonly limit?: number
+}
+
+function roleQuery(filters: RoleFilters): QueryParameters {
+  return { q: filters.term, status: filters.statuses, limit: filters.limit }
+}
+
+export function useRoles(
+  filters: RoleFilters = {},
+  options: ListOptions = {},
+): RecordListResult<Role> {
+  return roles.useList(roleQuery(filters), options)
+}
+
+export function useRole(id: string | undefined): RecordResult<Role> {
+  return roles.useRecord(id)
+}
+
+export function useCreateRole(): MutationResult<CreateRoleInput, Role> {
+  return roles.useCreate()
+}
+
+export function useUpdateRole(): MutationResult<UpdateArguments<RoleInput>, Role> {
+  return roles.useUpdate()
+}
+
+export function useDeleteRole(): MutationResult<string, void> {
+  return roles.useRemove()
+}

package/src/api/resources/search.ts

@@ -0,0 +1,49 @@
+import { searchResultsSchema } from '@kelpie/schemas'
+import type { SearchResults } from '@kelpie/schemas'
+import { useQuery } from '@tanstack/react-query'
+
+import { useApiClient } from '../context.ts'
+import { toError } from '../errors.ts'
+
+/**
+ * `/v1/search`, read-only: nine collections in one request.
+ *
+ * Not a `createResourceHooks` resource, for the same reason the dashboard is not.
+ * There is no collection to page, no id in a path, and no write.
+ *
+ * Nothing invalidates this key. Results are derived from records other pages own,
+ * so listing the writes that could change one would mean naming most of the API.
+ * A search is re-run by typing, which is a new key.
+ */
+
+/** How many results each group carries. The total beside each group stays exact. */
+const GROUP_LIMIT = 10
+
+export interface SearchState {
+  readonly results: SearchResults | undefined
+  readonly isLoading: boolean
+  readonly error: Error | null
+}
+
+/**
+ * @param term What was typed. An empty one asks nothing: the query is disabled
+ *   rather than sent, because `?q=` is required and a blank one is a 422.
+ */
+export function useSearch(term: string): SearchState {
+  const client = useApiClient()
+  const trimmed = term.trim()
+  const enabled = trimmed.length > 0
+
+  const result = useQuery({
+    queryKey: ['search', trimmed],
+    queryFn: () => client.get('/search', searchResultsSchema.parse, { q: trimmed, limit: GROUP_LIMIT }),
+    enabled,
+  })
+
+  return {
+    results: result.data,
+    // A disabled query stays pending forever, which is not the same as loading.
+    isLoading: result.isPending && enabled,
+    error: toError(result.error),
+  }
+}

package/src/api/resources/session.ts

@@ -0,0 +1,220 @@
+import {
+  confirmPasswordResetBody,
+  createWorkspaceBody,
+  logInBody,
+  requestPasswordResetBody,
+  sessionSchema,
+  signUpBody,
+  signedInAccountSchema,
+  workspaceSchema,
+} from '@kelpie/schemas'
+import type {
+  ConfirmPasswordResetInput,
+  CreateWorkspaceInput,
+  LogInInput,
+  RequestPasswordResetInput,
+  Session,
+  SignUpInput,
+  SignedInAccount,
+  Workspace,
+} from '@kelpie/schemas'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+
+import { ApiError } from '../client.ts'
+import type { ApiClient } from '../client.ts'
+import { useApiClient } from '../context.ts'
+import { toError } from '../errors.ts'
+import type { MutationResult } from '../resource.ts'
+import { asMutationResult } from './mutation.ts'
+
+/**
+ * Who the browser is signed in as.
+ *
+ * Not a CRM resource, so it does not go through `createResourceHooks`: there is
+ * no list, no id, and a `401` is an answer rather than a failure.
+ *
+ * Signing in or out changes which workspace every other cached query belongs to,
+ * so both clear the whole cache. Leaving one person's People page in the cache
+ * for the next person to sign in would be a data leak, not a stale render.
+ */
+
+const SESSION_KEY = ['session'] as const
+
+function sessionQuery(client: ApiClient): {
+  queryKey: typeof SESSION_KEY
+  queryFn: () => Promise<Session>
+  retry: false
+  staleTime: 0
+} {
+  return {
+    queryKey: SESSION_KEY,
+    queryFn: () => client.get('/auth/me', sessionSchema.parse),
+    // A 401 is the answer "signed out". Retrying it is pointless, and every
+    // remount should ask again rather than trust a cached identity.
+    retry: false,
+    staleTime: 0,
+  }
+}
+
+export interface SessionState {
+  readonly session: Session | undefined
+  readonly isLoading: boolean
+  /** The service answered `401`. Distinct from a network failure, which is `error`. */
+  readonly isSignedOut: boolean
+  /** Signed in, but the account has no workspace yet. Every CRM endpoint answers `403` until it does. */
+  readonly needsWorkspace: boolean
+  readonly error: Error | null
+}
+
+export function useSession(): SessionState {
+  const client = useApiClient()
+  const result = useQuery(sessionQuery(client))
+  const isSignedOut = result.error instanceof ApiError && result.error.status === 401
+
+  return {
+    session: result.data,
+    isLoading: result.isPending,
+    isSignedOut,
+    needsWorkspace: result.data !== undefined && result.data.workspaceId === null,
+    error: isSignedOut ? null : toError(result.error),
+  }
+}
+
+export function useLogIn(): MutationResult<LogInInput, SignedInAccount> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: (input: LogInInput) =>
+      client.post('/auth/login', logInBody(input), signedInAccountSchema.parse),
+    onSuccess: async () => {
+      queryClient.clear()
+      await queryClient.fetchQuery(sessionQuery(client))
+    },
+  })
+
+  return asMutationResult(mutation)
+}
+
+/**
+ * Creates the account and signs the browser in, because `POST /v1/auth/signup`
+ * sets the session cookie itself.
+ *
+ * The cache is cleared for the same reason sign-in clears it: whatever is in it
+ * belongs to whoever was here before.
+ */
+export function useSignUp(): MutationResult<SignUpInput, SignedInAccount> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: (input: SignUpInput) =>
+      client.post('/auth/signup', signUpBody(input), signedInAccountSchema.parse),
+    onSuccess: async () => {
+      queryClient.clear()
+      await queryClient.fetchQuery(sessionQuery(client))
+    },
+  })
+
+  return asMutationResult(mutation)
+}
+
+export function useLogOut(): MutationResult<void, void> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: () => client.postEmpty('/auth/logout'),
+    // No refetch afterwards. The caller sends the browser to the sign-in page,
+    // and the next protected route asks for the session itself.
+    onSettled: () => {
+      queryClient.clear()
+    },
+  })
+
+  return asMutationResult(mutation)
+}
+
+/** Where a reset email lands. `ResetPasswordPage` reads the token out of the query string. */
+export function resetUrlTemplate(origin: string): string {
+  return `${origin}/reset-password?token={token}`
+}
+
+/**
+ * Asks for a reset link.
+ *
+ * Answers `202` whether or not the address is registered, and the page says the
+ * same thing either way. A caller that could tell the difference would have an
+ * account-existence oracle.
+ *
+ * Nothing in the cache changes: this signs nobody in and ends no session.
+ */
+export function useRequestPasswordReset(): MutationResult<RequestPasswordResetInput, void> {
+  const client = useApiClient()
+  const mutation = useMutation({
+    mutationFn: (input: RequestPasswordResetInput) =>
+      client.postEmpty('/auth/password-reset', requestPasswordResetBody(input)),
+  })
+
+  return asMutationResult(mutation)
+}
+
+/**
+ * Spends a reset token on a new password.
+ *
+ * The service ends every session the account had, this browser included, so the
+ * caller sends the reader to sign in rather than into the app.
+ */
+export function useConfirmPasswordReset(): MutationResult<ConfirmPasswordResetInput, void> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: (input: ConfirmPasswordResetInput) =>
+      client.postEmpty('/auth/password-reset/confirm', confirmPasswordResetBody(input)),
+    onSuccess: () => {
+      queryClient.clear()
+    },
+  })
+
+  return asMutationResult(mutation)
+}
+
+/**
+ * Joins the workspace an invitation names.
+ *
+ * Like creating one, this moves the session, so the whole cache goes: the next
+ * page belongs to a different workspace than the one just cached.
+ */
+export function useAcceptInvite(): MutationResult<{ readonly token: string }, Workspace> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: ({ token }: { readonly token: string }) =>
+      client.post('/invites/accept', { token }, workspaceSchema.parse),
+    onSuccess: async () => {
+      queryClient.clear()
+      await queryClient.fetchQuery(sessionQuery(client))
+    },
+  })
+
+  return asMutationResult(mutation)
+}
+
+/**
+ * Creates the account's first workspace.
+ *
+ * Signup makes an account and nothing else (`onboarding.md`), so without this a
+ * new account reaches the app and gets `403` from every CRM endpoint.
+ */
+export function useCreateWorkspace(): MutationResult<CreateWorkspaceInput, Workspace> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: (input: CreateWorkspaceInput) =>
+      client.post('/workspaces', createWorkspaceBody(input), workspaceSchema.parse),
+    // Creating a workspace moves the session into it, so the session is stale.
+    onSuccess: async () => {
+      await queryClient.fetchQuery(sessionQuery(client))
+    },
+  })
+
+  return asMutationResult(mutation)
+}
+