Skip to main content

Stages

A shared package that contains queries and types for stages.

Usage​

This package is available to be imported into your module.

import { AccountStage } from '@shared/stages'

General remarks​

When working with Stages, it's important to be aware that stages can be inactive. Although inactive stages are valid and can be set as an Account's stage, they mostly should't be available for users to pick. This package provides functions that make it easier to guard this behavior.

The query results are by default cached for duration of the DEFAULT_CACHE_DURATION const.

Account Stages - useAccountStagesQuery​

Note: This hook is subject to pagination, bringing a risk of not fetching all stages object within one page. If you want to ensure all stages are fetched, the private API queries useActiveAccountStagesQuery and useAccountStagesQuery are recommended to be used instead.

Fetches the list of account stages from the public-api account_stages endpoint, wrapped in a ResponseApi object.

You are able to pass an optional set of query params and optionally override the underlying UseQueryOptions.

Person Stages - usePersonStagesQuery​

All of the above applies to the usePersonStagesQuery hook as well just taking into consideration that it fetches person stages from the public-api person_stages endpoint instead.

Person Stages - getPersonStages​

This function behaves in the same way as the usePersonStagesQuery hook, but it's a regular function that can be used in non-React contexts.


```typescript
import { useAccountStagesQuery } from '@shared/stages'

const { data: { data: accountStages = [] } = {}, isInitialLoading } = useAccountStagesQuery(queryParams)

Exported Types​

TypeDescription
AccountStageAccountStage resource returned by our public and private API
PersonStagePersonStage resource returned by our public and private API

Exported Utils​

stagesFixtures​

Fixtures of stages and its requests for testing purposes.

import { stagesFixtures } from '@shared/stages'

const stagesFromApi = stagesFixtures.stagesListResponse

nock(/localhost/)
  .get('/v2/account_stages')
  .query({ sort_by: 'order', sort_direction: 'asc' })
  .reply(200, stagesFromApi)

Private API​

Usage​

import { privateAccountStagesApi } from '@shared/stages'

Exported Private Queries​

Account Stages - useActiveAccountStagesQuery​

Fetches the complete list of account stages from the private API company_stages endpoint and selects only active ones.

Given only active stages should be available to set as the value of an Account's Stage, this query is recommended to be used over useAccountStagesQuery.

import { privateAccountStagesApi } from '@shared/stages'

const { data: activeAccountStages = [], isInitialLoading } = privateAccountStagesApi.queries.useActiveAccountStagesQuery()

Account Stages - useAccountStagesQuery​

Note: Before using it in the application, ensure that inactive values should be available in the given place. Otherwise, consider using useActiveAccountStagesQuery

This function behaves similarly to useActiveAccountStagesQuery with one difference - it returns all stages (inactive + active).

import { privateAccountStagesApi } from '@shared/stages'

const { data: accountStages = [], isInitialLoading } = privateAccountStagesApi.queries.useAccountStagesQuery()

Person Stages - useActivePersonStagesQuery​

Fetches the complete list of person stages from the private API cadence_stages endpoint and selects only active ones.

Given only active stages should be available to set as the value of an Person's Stage, this query is recommended to be used over usePersonStagesQuery.

import { privatePersonStagesApi } from '@shared/stages'

const { data: activePersonStages = [], isInitialLoading } = privatePersonStagesApi.queries.useActivePersonStagesQuery()

Person Stages - usePersonStagesQuery​

Note: Before using it in the application, ensure that inactive values should be available in the given place. Otherwise, consider using useActivePersonStagesQuery

This function behaves similarly to useActivePersonStagesQuery with one difference - it returns all stages (inactive + active).

import { privatePersonStagesApi } from '@shared/stages'

const { data: personStages = [], isInitialLoading } = privatePersonStagesApi.queries.usePersonStagesQuery()

Exported Hooks​

Account Stages - useActiveAccountStagesForDropdown​

Retrieve list of AccountStages for the purpose of using them as option list in a dropdown.

The list will include:

  • all active stages
  • current stage (regardless if it's active or inactive)

This hook handles the case when the current stage value is inactive, which otherwise wouldn't be included in the list of active stages.

  import { privateAccountStagesApi } from '@shared/stages'

  const { data: stagesForDropdown = [], isLoading: isLoadingActiveStages } =
    privateAccountStagesApi.hooks.useActiveAccountStagesForDropdown({
      companyStageId: company?.company_stage_id,
      enabled: Boolean(company),
    })

Person Stages - useActivePersonStagesForDropdown​

Retrieve list of PersonStages for the purpose of using them as option list in a dropdown.

The list will include:

  • all active stages
  • current stage (regardless if it's active or inactive)

This hook handles the case when the current stage value is inactive, which otherwise wouldn't be included in the list of active stages.

  import { privatePersonStagesApi } from '@shared/stages'

  const { data: stagesForDropdown = [], isLoading: isLoadingActiveStages } =
    privatePersonStagesApi.hooks.useActivePersonStagesForDropdown({
      companyStageId: company?.company_stage_id,
      enabled: Boolean(company),
    })