clarion-shared-types 1.0.90 → 1.0.91

package/dist/types/modules/support/interfaces/support-configuration.dto.d.ts

@@ -0,0 +1,244 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { SupportProviderCapability, SupportProviderCode, SupportQueueAssignmentStrategy, SupportRelatedEntityType, SupportRoutingMatchType, SupportSlaClock, SupportTeamMemberRole, SupportTicketChannel, SupportTicketPriority } from '../enums/support-enums';
+export interface SupportCategoryDto {
+    id: string;
+    organizationId: number | null;
+    parentId: string | null;
+    name: string;
+    code: string;
+    description: string | null;
+    defaultPriority: SupportTicketPriority | null;
+    defaultQueueId: string | null;
+    expectedRelatedEntityType: SupportRelatedEntityType | null;
+    displayOrder: number;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateSupportCategoryDto {
+    name: string;
+    code: string;
+    description?: string;
+    parentId?: string;
+    defaultPriority?: SupportTicketPriority;
+    defaultQueueId?: string;
+    expectedRelatedEntityType?: SupportRelatedEntityType;
+    displayOrder?: number;
+    organizationId?: number;
+}
+export type UpdateSupportCategoryDto = Partial<Omit<CreateSupportCategoryDto, 'code' | 'organizationId'>> & {
+    active?: boolean;
+};
+export interface SupportQueueDto {
+    id: string;
+    organizationId: number;
+    controlCentreId: number | null;
+    countryCode: CountryCode | null;
+    name: string;
+    code: string;
+    description: string | null;
+    teamId: string | null;
+    teamName: string | null;
+    assignmentStrategy: SupportQueueAssignmentStrategy;
+    slaPolicyId: string | null;
+    displayOrder: number;
+    active: boolean;
+    /** Live counts, filled on a list read so a supervisor sees the board at a glance. */
+    openTicketCount?: number;
+    unassignedTicketCount?: number;
+    breachedTicketCount?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateSupportQueueDto {
+    name: string;
+    code: string;
+    description?: string;
+    teamId?: string;
+    countryCode?: CountryCode;
+    controlCentreId?: number;
+    assignmentStrategy?: SupportQueueAssignmentStrategy;
+    slaPolicyId?: string;
+    displayOrder?: number;
+    organizationId?: number;
+}
+export type UpdateSupportQueueDto = Partial<Omit<CreateSupportQueueDto, 'code' | 'organizationId'>> & {
+    active?: boolean;
+};
+export interface SupportTeamDto {
+    id: string;
+    organizationId: number;
+    name: string;
+    code: string;
+    description: string | null;
+    supervisorUserIds: number[];
+    active: boolean;
+    memberCount?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateSupportTeamDto {
+    name: string;
+    code: string;
+    description?: string;
+    supervisorUserIds?: number[];
+    organizationId?: number;
+}
+export type UpdateSupportTeamDto = Partial<Omit<CreateSupportTeamDto, 'code' | 'organizationId'>> & {
+    active?: boolean;
+};
+export interface SupportTeamMemberDto {
+    id: string;
+    teamId: string;
+    userId: number;
+    userName: string | null;
+    role: SupportTeamMemberRole;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface UpsertSupportTeamMemberDto {
+    userId: number;
+    role: SupportTeamMemberRole;
+    active?: boolean;
+}
+export interface SupportSlaPolicyTargetDto {
+    priority: SupportTicketPriority;
+    firstResponseMinutes: number;
+    resolutionMinutes: number;
+    clock: SupportSlaClock;
+}
+export interface SupportBusinessCalendarDto {
+    /** ISO weekday numbers, Monday = 1. */
+    workingDays: number[];
+    startMinuteOfDay: number;
+    endMinuteOfDay: number;
+    timezone: string | null;
+    holidays: string[];
+}
+export interface SupportSlaPolicyDto {
+    id: string;
+    organizationId: number | null;
+    name: string;
+    description: string | null;
+    targets: SupportSlaPolicyTargetDto[];
+    businessCalendar: SupportBusinessCalendarDto | null;
+    isDefault: boolean;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateSupportSlaPolicyDto {
+    name: string;
+    description?: string;
+    targets: SupportSlaPolicyTargetDto[];
+    businessCalendar?: SupportBusinessCalendarDto;
+    isDefault?: boolean;
+    organizationId?: number;
+}
+export type UpdateSupportSlaPolicyDto = Partial<Omit<CreateSupportSlaPolicyDto, 'organizationId'>> & {
+    active?: boolean;
+};
+export interface SupportRoutingRuleDto {
+    id: string;
+    organizationId: number;
+    name: string;
+    matchType: SupportRoutingMatchType;
+    matchCategoryId: string | null;
+    matchPriority: SupportTicketPriority | null;
+    matchChannel: SupportTicketChannel | null;
+    matchCountryCode: CountryCode | null;
+    matchControlCentreId: number | null;
+    matchAppId: string | null;
+    matchRelatedEntityType: SupportRelatedEntityType | null;
+    targetQueueId: string;
+    targetQueueName: string | null;
+    forcePriority: SupportTicketPriority | null;
+    /** Lower runs first. First match wins - there is no scoring. */
+    priority: number;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateSupportRoutingRuleDto {
+    name: string;
+    matchType: SupportRoutingMatchType;
+    matchCategoryId?: string;
+    matchPriority?: SupportTicketPriority;
+    matchChannel?: SupportTicketChannel;
+    matchCountryCode?: CountryCode;
+    matchControlCentreId?: number;
+    matchAppId?: string;
+    matchRelatedEntityType?: SupportRelatedEntityType;
+    targetQueueId: string;
+    forcePriority?: SupportTicketPriority;
+    priority?: number;
+    organizationId?: number;
+}
+export type UpdateSupportRoutingRuleDto = Partial<Omit<CreateSupportRoutingRuleDto, 'organizationId'>> & {
+    active?: boolean;
+};
+/** One non-secret setting an adapter needs, described so a form can render it. */
+export interface SupportProviderConfigFieldDto {
+    key: string;
+    label: string;
+    description: string | null;
+    type: 'string' | 'number' | 'boolean' | 'select';
+    required: boolean;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    example: string | null;
+    defaultValue: string | number | boolean | null;
+}
+/**
+ * A credential the adapter needs, described by NAME only.
+ *
+ * The form collects the REFERENCE - the name of a secret in the deployment's
+ * secret store - never the credential. Nothing in the platform accepts a
+ * helpdesk API token over HTTP: a token typed into a browser is a token in a
+ * browser history, a proxy log and somebody's clipboard.
+ */
+export interface SupportProviderCredentialFieldDto {
+    key: string;
+    label: string;
+    description: string | null;
+    required: boolean;
+}
+export interface SupportProviderDescriptorDto {
+    code: SupportProviderCode;
+    name: string;
+    description: string;
+    capabilities: SupportProviderCapability[];
+    allowedHosts: string[];
+    available: boolean;
+    unavailableReason: string | null;
+    configFields: SupportProviderConfigFieldDto[];
+    credentialFields: SupportProviderCredentialFieldDto[];
+    verifiesWebhookSignature: boolean;
+    webhookPath: string | null;
+}
+/**
+ * Which helpdesk the deployment is running, as the admin sees it.
+ *
+ * Read-only on purpose. Switching provider is a deployment decision with a
+ * documented migration procedure, not a button - a screen that flipped the
+ * platform's helpdesk in one click would orphan every open ticket.
+ */
+export interface SupportProviderStatusDto {
+    activeProvider: SupportProviderCode;
+    providers: SupportProviderDescriptorDto[];
+    pendingSyncCount: number;
+    deadLetterSyncCount: number;
+    circuitOpen: boolean;
+    lastSuccessfulSyncAt: string | null;
+    lastFailedSyncAt: string | null;
+}
+export interface SupportProviderConnectionTestResultDto {
+    provider: SupportProviderCode;
+    success: boolean;
+    message: string;
+    latencyMs: number | null;
+    checkedAt: string;
+}

package/dist/types/modules/support/interfaces/support-reports.dto.d.ts

@@ -0,0 +1,146 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { CustomerFeedbackStatus, CustomerFeedbackType, SupportRealtimeEventType, SupportSlaState, SupportTicketChannel, SupportTicketMessageType, SupportTicketPriority, SupportTicketStatus } from '../enums/support-enums';
+/** A count against a dimension value. The shape every breakdown uses. */
+export interface SupportMetricBucketDto {
+    key: string;
+    /** Resolved server-side, so no chart has to own a label map. */
+    label: string;
+    count: number;
+}
+/** A count at a point in time, for the trend charts. */
+export interface SupportTimeSeriesPointDto {
+    at: string;
+    count: number;
+}
+/**
+ * The support overview.
+ *
+ * Durations are in MINUTES throughout. One unit across the whole contract,
+ * because a mixed seconds-and-minutes API is how a dashboard ends up silently
+ * reporting a sixty-fold error.
+ */
+export interface SupportDashboardMetricsDto {
+    from: string;
+    to: string;
+    totalTickets: number;
+    newTickets: number;
+    openTickets: number;
+    resolvedTickets: number;
+    closedTickets: number;
+    unassignedTickets: number;
+    breachedTickets: number;
+    atRiskTickets: number;
+    byStatus: SupportMetricBucketDto[];
+    byPriority: SupportMetricBucketDto[];
+    byChannel: SupportMetricBucketDto[];
+    byCategory: SupportMetricBucketDto[];
+    byQueue: SupportMetricBucketDto[];
+    byCountry: SupportMetricBucketDto[];
+    /** Populated only for a super-admin, the only caller who spans tenants. */
+    byOrganization: SupportMetricBucketDto[];
+    firstResponseComplianceRate: number;
+    resolutionComplianceRate: number;
+    slaBreachCount: number;
+    averageFirstResponseMinutes: number | null;
+    averageResolutionMinutes: number | null;
+    reopenRate: number;
+    feedbackCount: number;
+    averageRating: number | null;
+    feedbackByType: SupportMetricBucketDto[];
+    feedbackResponseRate: number;
+    feedbackConversionRate: number;
+    ticketsCreatedTrend: SupportTimeSeriesPointDto[];
+    ticketsResolvedTrend: SupportTimeSeriesPointDto[];
+}
+/** One agent's board. */
+export interface SupportAgentDashboardMetricsDto {
+    agentUserId: number;
+    from: string;
+    to: string;
+    assignedToMe: number;
+    overdue: number;
+    atRisk: number;
+    waitingOnCustomer: number;
+    waitingOnInternalTeam: number;
+    resolvedInRange: number;
+    closedInRange: number;
+    averageFirstResponseMinutes: number | null;
+    averageResolutionMinutes: number | null;
+    /** Assigned but never replied to. The number a supervisor actually acts on. */
+    awaitingFirstResponse: number;
+}
+/** Feedback analytics, which stand alone because feedback is its own domain. */
+export interface SupportFeedbackAnalyticsDto {
+    from: string;
+    to: string;
+    total: number;
+    byType: SupportMetricBucketDto[];
+    byStatus: SupportMetricBucketDto[];
+    byCountry: SupportMetricBucketDto[];
+    byOrganization: SupportMetricBucketDto[];
+    byApp: SupportMetricBucketDto[];
+    byAppVersion: SupportMetricBucketDto[];
+    byPlatform: SupportMetricBucketDto[];
+    bySentiment: SupportMetricBucketDto[];
+    averageRating: number | null;
+    ratingDistribution: SupportMetricBucketDto[];
+    responseRate: number;
+    conversionRate: number;
+    volumeTrend: SupportTimeSeriesPointDto[];
+}
+/** Filters every support report accepts. */
+export interface SupportReportQueryParams {
+    from?: string;
+    to?: string;
+    organizationId?: number;
+    controlCentreId?: number;
+    countryCode?: CountryCode;
+    queueId?: string;
+    teamId?: string;
+    categoryId?: string;
+    agentUserId?: number;
+    status?: SupportTicketStatus;
+    priority?: SupportTicketPriority;
+    channel?: SupportTicketChannel;
+    feedbackType?: CustomerFeedbackType;
+    feedbackStatus?: CustomerFeedbackStatus;
+    granularity?: 'DAY' | 'WEEK' | 'MONTH';
+}
+/**
+ * The live update the socket delivers.
+ *
+ * The payload is client-safe and minimal - enough to update a row or append a
+ * bubble, never enough to be an unauthorized read. An internal note reaches only
+ * the queue and agent rooms, and its body is not in the envelope at all: a
+ * client that needs it re-reads the ticket through the authorized REST path.
+ */
+export interface SupportRealtimeEnvelopeDto {
+    eventId: string;
+    eventType: SupportRealtimeEventType;
+    occurredAt: string;
+    organizationId: number;
+    controlCentreId: number | null;
+    rooms: string[];
+    ticketId?: string;
+    ticketNumber?: string;
+    feedbackId?: string;
+    actorUserId: number | null;
+    payload: SupportRealtimePayloadDto;
+}
+export interface SupportRealtimePayloadDto {
+    status?: SupportTicketStatus;
+    previousStatus?: SupportTicketStatus | null;
+    priority?: SupportTicketPriority;
+    assignedAgentId?: number | null;
+    queueId?: string | null;
+    messageId?: string;
+    messageType?: SupportTicketMessageType;
+    customerVisible?: boolean;
+    authorName?: string | null;
+    firstResponseSlaState?: SupportSlaState;
+    resolutionSlaState?: SupportSlaState;
+    externalSyncPending?: boolean;
+    externalSyncFailed?: boolean;
+    /** Server time the record last changed, so a client can discard a stale update. */
+    updatedAt?: string;
+}

package/dist/types/modules/support/interfaces/support-sync.dto.d.ts

@@ -0,0 +1,92 @@
+import { SupportProviderCode, SupportSyncEntityType, SupportSyncFailureReason, SupportSyncOperation, SupportSyncStatus, SupportWebhookStatus } from '../enums/support-enums';
+/** One unit of outbound work against a helpdesk, as the sync dashboard shows it. */
+export interface SupportProviderSyncDto {
+    id: string;
+    organizationId: number;
+    provider: SupportProviderCode;
+    entityType: SupportSyncEntityType;
+    entityId: string;
+    ticketId: string | null;
+    ticketNumber: string | null;
+    externalId: string | null;
+    operation: SupportSyncOperation;
+    status: SupportSyncStatus;
+    attempts: number;
+    maxAttempts: number;
+    lastAttemptAt: string | null;
+    nextAttemptAt: string | null;
+    failureReason: SupportSyncFailureReason | null;
+    errorCode: string | null;
+    /** Already scrubbed and length-capped server-side. Safe to render. */
+    errorMessage: string | null;
+    correlationId: string | null;
+    /** How long the row has been outstanding, so the list can sort by pain. */
+    ageMinutes: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A webhook delivery from a helpdesk. */
+export interface SupportWebhookEventDto {
+    id: string;
+    provider: SupportProviderCode;
+    externalEventId: string;
+    externalEventType: string | null;
+    ticketId: string | null;
+    externalTicketId: string | null;
+    status: SupportWebhookStatus;
+    statusReason: string | null;
+    receivedAt: string;
+    processedAt: string | null;
+    durationMs: number | null;
+}
+/** What reconciling one ticket against the provider found and did. */
+export interface SupportReconciliationResultDto {
+    ticketId: string;
+    ticketNumber: string;
+    provider: SupportProviderCode;
+    externalTicketId: string | null;
+    inSync: boolean;
+    differences: string[];
+    applied: string[];
+    /** Left alone for a human, with the reason. Reconciliation never guesses. */
+    unresolved: string[];
+    messagesImported: number;
+    reconciledAt: string;
+}
+/** Headline numbers for the synchronization panel. */
+export interface SupportSyncHealthDto {
+    provider: SupportProviderCode;
+    pending: number;
+    inProgress: number;
+    failed: number;
+    deadLetter: number;
+    succeededLastHour: number;
+    circuitOpen: boolean;
+    oldestPendingAgeMinutes: number | null;
+    lastSuccessfulSyncAt: string | null;
+    lastFailedSyncAt: string | null;
+}
+export interface RetrySupportSyncDto {
+    reason?: string;
+    /** Off by default: a row that failed eight times usually needs a fix, not eight more tries. */
+    resetAttempts?: boolean;
+}
+export interface ReconcileSupportTicketDto {
+    /** Defaults to true, so an operator sees what would change before it changes. */
+    dryRun?: boolean;
+    importMissingMessages?: boolean;
+}
+export interface SupportSyncQueryParams {
+    page?: number;
+    limit?: number;
+    status?: SupportSyncStatus;
+    operation?: SupportSyncOperation;
+    entityType?: SupportSyncEntityType;
+    failureReason?: SupportSyncFailureReason;
+    provider?: SupportProviderCode;
+    ticketId?: string;
+    organizationId?: number;
+    needsAttentionOnly?: boolean;
+    from?: string;
+    to?: string;
+}