@ikatec/digisac-api-sdk 4.4.1 → 4.5.1

package/src/apis/pipeline/PipelineApi.ts

@@ -1,6 +1,28 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { Pipeline, CreatePipelinePayload, UpdatePipelinePayload } from './types'
+import type {
+  CreatePipelineAutomationPayload,
+  CreatePipelinePayload,
+  CreatePipelineStagePayload,
+  DeletePipelineStagePayload,
+  DeletePipelineStageResult,
+  DeletePipelineStatusPayload,
+  ExportPipelinePayload,
+  Pipeline,
+  PipelineAutomation,
+  PipelineRecord,
+  PipelineStage,
+  PipelineStageRefusal,
+  PipelineStageStatusWithCount,
+  PipelineStageTotals,
+  PipelineStageTotalsFilters,
+  PipelineStatusRef,
+  PipelinesWithTotals,
+  PipelinesWithTotalsQuery,
+  UpdatePipelineAutomationPayload,
+  UpdatePipelinePayload,
+  UpdatePipelineStagePayload,
+} from './types'
 
 export class PipelineApi extends BaseCrudApi<
   Pipeline,
@@ -10,4 +32,255 @@ export class PipelineApi extends BaseCrudApi<
   constructor(client: ApiClient) {
     super(client, '/pipelines')
   }
+
+  /**
+   * Adds a stage (with its statuses and reasons) to a pipeline. Resolves to the stage as stored,
+   * without the statuses/reasons, or to a refusal code with 200: `'STAGES_LIMIT'` (the pipeline
+   * already has 10 stages) or `'STAGE_ALREADY_EXIST'` (same name).
+   * @permissions pipelines.update
+   */
+  createStage(
+    body: CreatePipelineStagePayload,
+    headers?: Record<string, string>,
+  ): Promise<PipelineStage | PipelineStageRefusal> {
+    return this.client.post<PipelineStage | PipelineStageRefusal, CreatePipelineStagePayload>(
+      `${this.basePath}/stage`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Updates a stage. `statuses` and `reasons` replace the whole set: items with `id` are kept
+   * and updated, items without it are created and the missing ones are deleted — omitting the
+   * lists deletes every status and reason of the stage. Resolves to the stage as stored, or to
+   * `'STAGE_ALREADY_EXIST'`.
+   * @permissions pipelines.update
+   */
+  updateStage(
+    id: string,
+    body: UpdatePipelineStagePayload,
+    headers?: Record<string, string>,
+  ): Promise<PipelineStage | 'STAGE_ALREADY_EXIST'> {
+    return this.client.put<PipelineStage | 'STAGE_ALREADY_EXIST', UpdatePipelineStagePayload>(
+      `${this.basePath}/stage/${id}`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Deletes a stage and moves its cards (see {@link DeletePipelineStagePayload}). Resolves to
+   * `'MESSAGE_STAGE_DELETED'`, or to `'PIPELINES_MIN_STAGES'` (nothing deleted) when the pipeline
+   * has only 2 stages. The backend also serves this under `PUT /pipelines/delete-stage/{id}`.
+   * @permissions pipelines.update
+   */
+  deleteStage(
+    id: string,
+    body: DeletePipelineStagePayload = {},
+    headers?: Record<string, string>,
+  ): Promise<DeletePipelineStageResult> {
+    return this.client.request<DeletePipelineStageResult, DeletePipelineStagePayload>(
+      'DELETE',
+      `${this.basePath}/stage/${id}`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Lists the statuses of every stage of a pipeline (`[]` for an unknown pipeline).
+   * @permissions pipelines.view
+   */
+  getStatuses(pipelineId: string, headers?: Record<string, string>): Promise<PipelineStatusRef[]> {
+    return this.client.get<PipelineStatusRef[]>(`${this.basePath}/statuses/${pipelineId}`, headers)
+  }
+
+  /**
+   * Gets a stage status with the number of cards using it. An unknown id resolves to
+   * `{ cardsCount: 0 }` with 200, not to an error.
+   * @permissions pipelines.view
+   */
+  getStatus(
+    id: string,
+    headers?: Record<string, string>,
+  ): Promise<PipelineStageStatusWithCount | { cardsCount: 0 }> {
+    return this.client.get<PipelineStageStatusWithCount | { cardsCount: 0 }>(
+      `${this.basePath}/status/${id}`,
+      headers,
+    )
+  }
+
+  /**
+   * Deletes a stage status, keeping its cards without status or moving them to another one.
+   * Resolves to `'MESSAGE_STATUS_DELETED'`.
+   * @permissions pipelines.view
+   */
+  deleteStatus(
+    id: string,
+    body: DeletePipelineStatusPayload,
+    headers?: Record<string, string>,
+  ): Promise<'MESSAGE_STATUS_DELETED'> {
+    return this.client.post<'MESSAGE_STATUS_DELETED', DeletePipelineStatusPayload>(
+      `${this.basePath}/delete-status/${id}`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Renames a stage status — same route as {@link deleteStatus}, without an `action`.
+   * Resolves to `'MESSAGE_STATUS_RENAMED'`; an empty name fails with 500.
+   * @permissions pipelines.view
+   */
+  renameStatus(
+    id: string,
+    newStatusName: string,
+    headers?: Record<string, string>,
+  ): Promise<'MESSAGE_STATUS_RENAMED'> {
+    return this.client.post<'MESSAGE_STATUS_RENAMED', { newStatusName: string }>(
+      `${this.basePath}/delete-status/${id}`,
+      { newStatusName },
+      headers,
+    )
+  }
+
+  /**
+   * Creates an automation of a pipeline. Resolves to the automation as stored.
+   * @permissions pipelines.update
+   */
+  createAutomation(
+    body: CreatePipelineAutomationPayload,
+    headers?: Record<string, string>,
+  ): Promise<PipelineAutomation> {
+    return this.client.post<PipelineAutomation, CreatePipelineAutomationPayload>(
+      `${this.basePath}/automations`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Updates an automation. Resolves to the automation as stored.
+   * @permissions pipelines.update
+   */
+  updateAutomation(
+    id: string,
+    body: UpdatePipelineAutomationPayload,
+    headers?: Record<string, string>,
+  ): Promise<PipelineAutomation> {
+    return this.client.put<PipelineAutomation, UpdatePipelineAutomationPayload>(
+      `${this.basePath}/automations/${id}`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Deletes an automation. Resolves with no content; an unknown id fails with 500.
+   * @permissions pipelines.update
+   */
+  deleteAutomation(id: string, headers?: Record<string, string>): Promise<void> {
+    return this.client.delete<void>(`${this.basePath}/automations/${id}`, headers)
+  }
+
+  /**
+   * Gets the automation of a pipeline — a single object (the first one found), or `[]` when
+   * the pipeline has none.
+   * @permissions pipelines.view
+   */
+  getAutomation(
+    pipelineId: string,
+    headers?: Record<string, string>,
+  ): Promise<PipelineAutomation | []> {
+    return this.client.get<PipelineAutomation | []>(
+      `${this.basePath}/automations/${pipelineId}`,
+      headers,
+    )
+  }
+
+  /**
+   * Copies a pipeline as `"<name> (copy)"`, with its stages, statuses, reasons and automations
+   * (not its departments). Resolves to the new pipeline as stored, without the stages.
+   * @permissions pipelines.view
+   */
+  duplicate(pipelineId: string, headers?: Record<string, string>): Promise<PipelineRecord> {
+    return this.client.post<PipelineRecord>(
+      `${this.basePath}/duplicate/${pipelineId}`,
+      undefined,
+      headers,
+    )
+  }
+
+  /**
+   * Archives a pipeline. Resolves to the pipeline with its stages and their card totals.
+   * @permissions pipelines.update
+   */
+  archive(id: string, headers?: Record<string, string>): Promise<Pipeline> {
+    return this.client.post<Pipeline, { archive: boolean }>(
+      `${this.basePath}/${id}/archive`,
+      { archive: true },
+      headers,
+    )
+  }
+
+  /**
+   * Restores an archived pipeline. Resolves to the pipeline with its stages and their totals.
+   * @permissions pipelines.update
+   */
+  unarchive(id: string, headers?: Record<string, string>): Promise<Pipeline> {
+    return this.client.post<Pipeline, { archive: boolean }>(
+      `${this.basePath}/${id}/archive`,
+      { archive: false },
+      headers,
+    )
+  }
+
+  /**
+   * Exports the cards of a pipeline as CSV text (`;` as the delimiter): a summary block
+   * followed by one row per card.
+   * @permissions pipelines.view
+   */
+  exportCsv(
+    id: string,
+    body: ExportPipelinePayload = {},
+    headers?: Record<string, string>,
+  ): Promise<string> {
+    return this.client.post<string, ExportPipelinePayload>(
+      `${this.basePath}/${id}/export`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Lists the pipelines of the account with their stages and card totals. Not paginated.
+   * @permissions pipelines.view
+   */
+  getManyWithTotals(
+    query?: PipelinesWithTotalsQuery,
+    headers?: Record<string, string>,
+  ): Promise<PipelinesWithTotals> {
+    return this.client.get<PipelinesWithTotals>(
+      `${this.basePath}/withTotals${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * Gets the card totals of a stage, optionally filtered like the board. Resolves to `null`
+   * for an unknown stage.
+   * @permissions pipelines.update OR pipelines.opportunity.update
+   */
+  getStageTotals(
+    stageId: string,
+    filters: PipelineStageTotalsFilters = {},
+    headers?: Record<string, string>,
+  ): Promise<PipelineStageTotals | null> {
+    return this.client.post<PipelineStageTotals | null, PipelineStageTotalsFilters>(
+      `${this.basePath}/stage-totals/${stageId}`,
+      filters,
+      headers,
+    )
+  }
 }

package/src/apis/pipeline/types.ts

@@ -1,4 +1,5 @@
 import type { Department } from '../departments/types'
+import type { WhereClause } from '../../core/types'
 
 export type PipelineStageStatus = {
   id: string
@@ -95,3 +96,164 @@ export type UpdatePipelinePayload = {
   goBack?: boolean
   permissionToViewCard?: boolean | null
 }
+
+/** Codes the stage routes answer (as a JSON string, with 200) instead of the stage. */
+export type PipelineStageRefusal = 'STAGES_LIMIT' | 'STAGE_ALREADY_EXIST'
+
+export type PipelineStageStatusInput = {
+  /** Send the `id` of an existing status to keep it on update; omit it to create one. */
+  id?: string
+  name: string
+  position: number
+}
+
+export type PipelineStageReasonInput = {
+  /** Send the `id` of an existing reason to keep it on update; omit it to create one. */
+  id?: string
+  name: string
+  position: number
+  isWon?: boolean
+}
+
+export type CreatePipelineStagePayload = {
+  /** Up to 255 characters; must not repeat the name of another stage of the pipeline. */
+  name: string
+  pipelineId: string
+  /** Must be truthy — the backend `required` rule refuses `0`. */
+  position: number
+  /** Up to 10. */
+  statuses?: PipelineStageStatusInput[]
+  /** Up to 20. */
+  reasons?: PipelineStageReasonInput[]
+}
+
+export type UpdatePipelineStagePayload = CreatePipelineStagePayload & {
+  /**
+   * The stage id. Send it: the duplicate-name check compares against the `id` of the body,
+   * so without it keeping the current name answers `'STAGE_ALREADY_EXIST'`.
+   */
+  id?: string
+}
+
+/**
+ * Where the cards of a deleted stage go:
+ * - `typeAction: 'move'` moves them to `idNewStage` (a stage of the same pipeline), clearing
+ *   status, reason and result;
+ * - without `typeAction`, they are archived and moved to the first stage of the pipeline.
+ */
+export type DeletePipelineStagePayload = {
+  typeAction?: 'move'
+  idNewStage?: string
+  /**
+   * Author of the card movements written by `'move'` — the backend reads it from the body, not
+   * from the token (the UI sends the logged user). Without it, moving a stage that has cards
+   * fails with 500 (`CardMovement.userId cannot be null`) after the cards were already moved,
+   * and the stage is kept.
+   */
+  user?: { id: string }
+}
+
+/** Answer of the stage deletion; `'PIPELINES_MIN_STAGES'` = refused, the pipeline keeps 2 stages. */
+export type DeletePipelineStageResult = 'MESSAGE_STAGE_DELETED' | 'PIPELINES_MIN_STAGES'
+
+export type PipelineStatusRef = { id: string; name: string }
+
+/** `GET /pipelines/status/{id}`: the status plus how many cards use it. */
+export type PipelineStageStatusWithCount = PipelineStageStatus & { cardsCount: number }
+
+/**
+ * What happens to the cards of a deleted status: `'keep-without-status'` clears their status,
+ * `'move-to-another'` sets `newStatusId` (not validated by the backend).
+ */
+export type DeletePipelineStatusPayload =
+  | { action: 'keep-without-status' }
+  | { action: 'move-to-another'; newStatusId: string }
+
+export type PipelineAutomationType = 'notification'
+
+export type PipelineAutomationConfig = {
+  notify?: 'high' | 'medium' | 'medium-high'
+  frequency?: 'daily' | 'weekly' | 'biweekly' | 'monthly'
+  day?: string
+  from?: { high?: string; medium?: string }
+  recipient?: 'admin' | 'owner' | 'both'
+}
+
+export type PipelineAutomation = {
+  id: string
+  pipelineId: string
+  type: PipelineAutomationType
+  isArchived: boolean | null
+  archivedAt: string | null
+  config: PipelineAutomationConfig
+  createdAt: string
+  updatedAt: string
+}
+
+export type CreatePipelineAutomationPayload = {
+  pipelineId: string
+  /** The backend does not validate it (any string is stored); `'notification'` is the only one used. */
+  type: PipelineAutomationType
+  config?: PipelineAutomationConfig
+  isArchived?: boolean
+}
+
+/** The backend validator requires `pipelineId` and `type` on update too. */
+export type UpdatePipelineAutomationPayload = CreatePipelineAutomationPayload
+
+/** Card date filters of the CSV export; the UI sends `'YYYY-MM-DD HH:mm:ss'`. */
+export type ExportPipelinePayload = {
+  /** Without both `createdAt*`, the range defaults to now (empty export). */
+  createdAtInit?: string
+  createdAtFinal?: string
+  /** With both `wonAt*`, only won cards are exported. */
+  wonAtInit?: string
+  wonAtFinal?: string
+}
+
+export type PipelinesWithTotalsQuery = {
+  /** `accountId` is always injected by the backend. `$and[].createdAt` filters the cards. */
+  where?: WhereClause<PipelineRecord>
+  order?: [string, 'ASC' | 'DESC'][]
+  limit?: number
+  /** `true` lists only the pipelines that are not archived. */
+  archive?: boolean
+}
+
+export type PipelineTotals = {
+  id: string
+  name: string
+  total: number | null
+  totalSuccess: number | null
+  totalFailed: number | null
+  /** A bigint, sent as a string. */
+  totalCards: string
+}
+
+/**
+ * Pipelines without stages are left out; there is no pagination. With a `createdAt` filter, only
+ * the stages that have matching cards are listed, but `totals` still has every stage.
+ */
+export type PipelinesWithTotals = {
+  data: (PipelineRecord & { stages: PipelineStage[]; totals: PipelineTotals[] })[]
+}
+
+/** Card filters of the stage totals (same as the board filters of the UI). */
+export type PipelineStageTotalsFilters = {
+  status?: { value: string }
+  service?: { id: string }
+  nameTitle?: string
+  /** `DD/MM/YYYY`. */
+  createdFrom?: string
+  createdUntil?: string
+  owner?: { id: string; value?: string }
+  wonFrom?: string
+  wonUntil?: string
+}
+
+export type PipelineStageTotals = PipelineStage & {
+  totalCards: number
+  totalCardsValue: number
+  totalWonCardsValue: number
+  totalLostCardsValue: number
+}

package/src/apis/tickets/types.ts

@@ -1,5 +1,6 @@
 import type { Contact } from '../contacts/types'
 import type { Department } from '../departments/types'
+import type { Message } from '../messages/types'
 import type { Service } from '../services/types'
 import type { User } from '../users/types'
 
@@ -23,6 +24,43 @@ export type TicketMetrics = {
   isActiveTicket?: boolean
 }
 
+export type TicketTransferAction = 'opened' | 'transferred' | 'closed'
+
+/**
+ * A step of the history of a ticket (opening, transfer, closing), as the `ticketTransfers` include of
+ * `GET /tickets/{id}` answers it. `byUserId` is who performed the step (null when there is no user, e.g. a bot).
+ *
+ * Inside `ticketTransfers`, the route whitelist only accepts `byUser`, `fromUser`, `toUser`, `fromDepartment` and
+ * `toDepartment`: `transferredMessage`, `firstMessage` and `lastMessage` are dropped in silence and come as `null`.
+ */
+export type TicketTransfer = {
+  id: string
+  action: TicketTransferAction | null
+  comments: string | null
+  fromDistribution: boolean
+  accountId: string
+  ticketId: string
+  byUserId: string | null
+  fromUserId: string | null
+  toUserId: string | null
+  fromDepartmentId: string | null
+  toDepartmentId: string | null
+  transferredMessageId: string | null
+  firstMessageId: string | null
+  lastMessageId: string | null
+  createdAt: string
+  updatedAt: string
+  // relationships
+  byUser?: User | null
+  fromUser?: User | null
+  toUser?: User | null
+  fromDepartment?: Department | null
+  toDepartment?: Department | null
+  transferredMessage?: Message | null
+  firstMessage?: Message | null
+  lastMessage?: Message | null
+}
+
 export type Ticket = {
   id: string
   isOpen: boolean
@@ -49,9 +87,10 @@ export type Ticket = {
   department?: Department
   user?: User | null
   service?: Service | null
+  ticketTransfers?: TicketTransfer[]
 }
 
-export type TicketRelationships = 'contact' | 'department' | 'user' | 'service'
+export type TicketRelationships = 'contact' | 'department' | 'user' | 'service' | 'ticketTransfers'
 
 export type CreateTicketPayload = {
   contactId: string