clarion-shared-types 1.0.89 → 1.0.91

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

@@ -0,0 +1,275 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { SupportMessageAuthorType, SupportMessageOrigin, SupportProviderCode, SupportRelatedEntityType, SupportSlaState, SupportSlaTarget, SupportTicketChannel, SupportTicketMessageType, SupportTicketPriority, SupportTicketSource, SupportTicketStatus } from '../enums/support-enums';
+/** A pointer to a record owned by another service. Type plus id, never a copy. */
+export interface SupportRelatedEntityDto {
+    type: SupportRelatedEntityType;
+    /** Text, because the owning services disagree on integer versus uuid. */
+    id: string;
+    /** Resolved for display; absent when it could not be resolved or may not be shown. */
+    label?: string | null;
+}
+/** Where one SLA clock stands. */
+export interface SupportSlaClockDto {
+    target: SupportSlaTarget;
+    state: SupportSlaState;
+    dueAt: string | null;
+    metAt: string | null;
+    /** Negative once breached. Computed server-side so no client re-derives a deadline. */
+    remainingMinutes: number | null;
+    pausedMinutes: number;
+}
+/**
+ * A support ticket as the admin and the customer app receive it.
+ *
+ * The `external*` fields are the only place a helpdesk's identifiers appear in
+ * the browser - never its payloads, never its URLs and never its credentials.
+ */
+export interface SupportTicketDto {
+    id: string;
+    ticketNumber: string;
+    organizationId: number;
+    controlCentreId: number | null;
+    countryCode: CountryCode;
+    appId: string | null;
+    createdByUserId: number;
+    customerUserId: number;
+    customerName: string | null;
+    assignedAgentId: number | null;
+    assignedAgentName: string | null;
+    assignedTeamId: string | null;
+    assignedTeamName: string | null;
+    queueId: string | null;
+    queueName: string | null;
+    categoryId: string | null;
+    categoryName: string | null;
+    subject: string;
+    description: string;
+    status: SupportTicketStatus;
+    priority: SupportTicketPriority;
+    channel: SupportTicketChannel;
+    source: SupportTicketSource;
+    tags: string[];
+    firstResponseDueAt: string | null;
+    resolutionDueAt: string | null;
+    firstRespondedAt: string | null;
+    resolvedAt: string | null;
+    closedAt: string | null;
+    reopenedAt: string | null;
+    firstResponseSlaState: SupportSlaState;
+    resolutionSlaState: SupportSlaState;
+    slaPolicyId: string | null;
+    /** Both clocks with their remaining time, so a chip needs no client arithmetic. */
+    slaClocks: SupportSlaClockDto[];
+    lastCustomerMessageAt: string | null;
+    lastAgentMessageAt: string | null;
+    messageCount: number;
+    reopenCount: number;
+    externalProvider: SupportProviderCode | null;
+    externalTicketId: string | null;
+    externalTicketNumber: string | null;
+    externalSyncPending: boolean;
+    externalSyncFailed: boolean;
+    externalLastSyncedAt: string | null;
+    relatedEntities: SupportRelatedEntityDto[];
+    sourceFeedbackId: string | null;
+    metadata: Record<string, unknown> | null;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** The row shape a ticket list returns. A subset, so a page stays small. */
+export interface SupportTicketSummaryDto {
+    id: string;
+    ticketNumber: string;
+    organizationId: number;
+    controlCentreId: number | null;
+    countryCode: CountryCode;
+    customerUserId: number;
+    customerName: string | null;
+    assignedAgentId: number | null;
+    assignedAgentName: string | null;
+    queueId: string | null;
+    queueName: string | null;
+    categoryId: string | null;
+    categoryName: string | null;
+    subject: string;
+    status: SupportTicketStatus;
+    priority: SupportTicketPriority;
+    channel: SupportTicketChannel;
+    firstResponseSlaState: SupportSlaState;
+    resolutionSlaState: SupportSlaState;
+    firstResponseDueAt: string | null;
+    resolutionDueAt: string | null;
+    lastCustomerMessageAt: string | null;
+    lastAgentMessageAt: string | null;
+    messageCount: number;
+    externalProvider: SupportProviderCode | null;
+    externalSyncPending: boolean;
+    externalSyncFailed: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A file on a ticket. The bytes live in clarion-dms; this is the reference. */
+export interface SupportTicketAttachmentDto {
+    id: string;
+    ticketId: string;
+    messageId: string | null;
+    documentId: number;
+    fileName: string;
+    mimeType: string;
+    sizeBytes: number;
+    uploadedByUserId: number | null;
+    fromProvider: boolean;
+    externalAttachmentId: string | null;
+    /**
+     * Short-lived and authorization-checked. Present only on a single-ticket
+     * read, never on a list. A provider's own attachment URL is never handed to
+     * a browser - those are frequently unauthenticated and permanent.
+     */
+    downloadUrl: string | null;
+    createdAt: string;
+}
+/** One entry in a ticket conversation. */
+export interface SupportTicketMessageDto {
+    id: string;
+    ticketId: string;
+    type: SupportTicketMessageType;
+    authorType: SupportMessageAuthorType;
+    authorUserId: number | null;
+    authorName: string | null;
+    body: string;
+    origin: SupportMessageOrigin;
+    externalProvider: SupportProviderCode | null;
+    externalMessageId: string | null;
+    attachments: SupportTicketAttachmentDto[];
+    /** True while the entry has not reached the helpdesk yet. Shown differently on purpose. */
+    externalSyncPending: boolean;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+}
+/** One recorded status change on the ticket timeline. */
+export interface SupportTicketStatusHistoryDto {
+    id: string;
+    ticketId: string;
+    fromStatus: SupportTicketStatus | null;
+    toStatus: SupportTicketStatus;
+    changedByUserId: number | null;
+    changedByName: string | null;
+    fromProvider: boolean;
+    reason: string | null;
+    createdAt: string;
+}
+/** One recorded assignment change. */
+export interface SupportTicketAssignmentHistoryDto {
+    id: string;
+    ticketId: string;
+    fromAgentId: number | null;
+    fromAgentName: string | null;
+    toAgentId: number | null;
+    toAgentName: string | null;
+    fromTeamId: string | null;
+    toTeamId: string | null;
+    fromQueueId: string | null;
+    toQueueId: string | null;
+    changedByUserId: number | null;
+    changedByName: string | null;
+    reason: string | null;
+    createdAt: string;
+}
+/** A ticket with everything the detail page renders, in one response. */
+export interface SupportTicketDetailsDto {
+    ticket: SupportTicketDto;
+    messages: SupportTicketMessageDto[];
+    attachments: SupportTicketAttachmentDto[];
+    statusHistory: SupportTicketStatusHistoryDto[];
+    assignmentHistory: SupportTicketAssignmentHistoryDto[];
+    /** The states this ticket may legally move to, so the UI offers only those. */
+    allowedStatuses: SupportTicketStatus[];
+}
+/** Create a ticket. Send an `Idempotency-Key` header so a retry is not a duplicate. */
+export interface CreateSupportTicketDto {
+    subject: string;
+    description: string;
+    categoryId?: string;
+    priority?: SupportTicketPriority;
+    channel?: SupportTicketChannel;
+    relatedEntities?: {
+        type: SupportRelatedEntityType;
+        id: string;
+    }[];
+    documentIds?: number[];
+    tags?: string[];
+    appId?: string;
+    countryCode?: CountryCode;
+    /** Super-admin only. */
+    organizationId?: number;
+    /** Agent raising a ticket for somebody else. */
+    customerUserId?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface UpdateSupportTicketDto {
+    subject?: string;
+    categoryId?: string;
+    queueId?: string;
+}
+export interface AssignSupportTicketDto {
+    assignedAgentId?: number;
+    assignedTeamId?: string;
+    queueId?: string;
+    reason?: string;
+}
+export interface ChangeSupportTicketStatusDto {
+    status: SupportTicketStatus;
+    reason?: string;
+    /** Optional note posted to the customer alongside the change. */
+    message?: string;
+}
+export interface ChangeSupportTicketPriorityDto {
+    priority: SupportTicketPriority;
+    reason?: string;
+}
+export interface CreateSupportTicketMessageDto {
+    body: string;
+    documentIds?: number[];
+}
+export interface SetSupportTicketTagsDto {
+    tags: string[];
+}
+export interface CloseSupportTicketDto {
+    message?: string;
+}
+export interface ReopenSupportTicketDto {
+    reason: string;
+}
+export interface AttachSupportDocumentsDto {
+    documentIds: number[];
+    messageId?: string;
+}
+/** Filters for a ticket list. Narrows what the caller may already see. */
+export interface SupportTicketQueryParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: string;
+    sortOrder?: 'ASC' | 'DESC';
+    status?: SupportTicketStatus;
+    activeOnly?: boolean;
+    priority?: SupportTicketPriority;
+    channel?: SupportTicketChannel;
+    countryCode?: CountryCode;
+    organizationId?: number;
+    controlCentreId?: number;
+    queueId?: string;
+    teamId?: string;
+    categoryId?: string;
+    assignedAgentId?: number;
+    unassignedOnly?: boolean;
+    customerUserId?: number;
+    slaState?: SupportSlaState;
+    breachedOnly?: boolean;
+    tag?: string;
+    externalProvider?: SupportProviderCode;
+    syncFailedOnly?: boolean;
+    from?: string;
+    to?: string;
+}

package/dist/types/modules/support/utils/support-display.util.d.ts

@@ -0,0 +1,67 @@
+import { CustomerFeedbackChannel, CustomerFeedbackSentiment, CustomerFeedbackStatus, CustomerFeedbackType, SupportMessageAuthorType, SupportProviderCapability, SupportProviderCode, SupportQueueAssignmentStrategy, SupportRelatedEntityType, SupportRoutingMatchType, SupportSlaClock, SupportSlaState, SupportSlaTarget, SupportSyncFailureReason, SupportSyncOperation, SupportSyncStatus, SupportTeamMemberRole, SupportTicketChannel, SupportTicketMessageType, SupportTicketPriority, SupportTicketSource, SupportTicketStatus, SupportWebhookStatus } from '../enums/support-enums';
+/**
+ * Human labels for the support enums.
+ *
+ * Kept in the shared package rather than in the admin app so every screen that
+ * shows a ticket - the list, the detail page, the queue board, the customer's
+ * own screen - names the same state the same way. An operator reading "Waiting
+ * on customer" in one place and "Pending reply" in another would reasonably
+ * assume they were different things.
+ */
+export declare const SUPPORT_TICKET_STATUS_LABELS: Readonly<Record<SupportTicketStatus, string>>;
+export declare const SUPPORT_TICKET_PRIORITY_LABELS: Readonly<Record<SupportTicketPriority, string>>;
+export declare const SUPPORT_TICKET_CHANNEL_LABELS: Readonly<Record<SupportTicketChannel, string>>;
+export declare const SUPPORT_TICKET_SOURCE_LABELS: Readonly<Record<SupportTicketSource, string>>;
+export declare const SUPPORT_TICKET_MESSAGE_TYPE_LABELS: Readonly<Record<SupportTicketMessageType, string>>;
+export declare const SUPPORT_MESSAGE_AUTHOR_TYPE_LABELS: Readonly<Record<SupportMessageAuthorType, string>>;
+export declare const SUPPORT_SLA_STATE_LABELS: Readonly<Record<SupportSlaState, string>>;
+export declare const SUPPORT_SLA_TARGET_LABELS: Readonly<Record<SupportSlaTarget, string>>;
+export declare const SUPPORT_SLA_CLOCK_LABELS: Readonly<Record<SupportSlaClock, string>>;
+export declare const CUSTOMER_FEEDBACK_TYPE_LABELS: Readonly<Record<CustomerFeedbackType, string>>;
+export declare const CUSTOMER_FEEDBACK_STATUS_LABELS: Readonly<Record<CustomerFeedbackStatus, string>>;
+export declare const CUSTOMER_FEEDBACK_CHANNEL_LABELS: Readonly<Record<CustomerFeedbackChannel, string>>;
+export declare const CUSTOMER_FEEDBACK_SENTIMENT_LABELS: Readonly<Record<CustomerFeedbackSentiment, string>>;
+export declare const SUPPORT_PROVIDER_LABELS: Readonly<Record<SupportProviderCode, string>>;
+export declare const SUPPORT_PROVIDER_CAPABILITY_LABELS: Readonly<Record<SupportProviderCapability, string>>;
+export declare const SUPPORT_SYNC_STATUS_LABELS: Readonly<Record<SupportSyncStatus, string>>;
+export declare const SUPPORT_SYNC_OPERATION_LABELS: Readonly<Record<SupportSyncOperation, string>>;
+/**
+ * Failure reasons in words an operator can act on.
+ *
+ * Each one says what to DO, not just what happened. "Provider rejected the
+ * request" tells nobody anything; "the helpdesk refused the request - check the
+ * ticket's category mapping" is a next step.
+ */
+export declare const SUPPORT_SYNC_FAILURE_REASON_LABELS: Readonly<Record<SupportSyncFailureReason, string>>;
+export declare const SUPPORT_WEBHOOK_STATUS_LABELS: Readonly<Record<SupportWebhookStatus, string>>;
+export declare const SUPPORT_RELATED_ENTITY_TYPE_LABELS: Readonly<Record<SupportRelatedEntityType, string>>;
+export declare const SUPPORT_QUEUE_ASSIGNMENT_STRATEGY_LABELS: Readonly<Record<SupportQueueAssignmentStrategy, string>>;
+export declare const SUPPORT_ROUTING_MATCH_TYPE_LABELS: Readonly<Record<SupportRoutingMatchType, string>>;
+export declare const SUPPORT_TEAM_MEMBER_ROLE_LABELS: Readonly<Record<SupportTeamMemberRole, string>>;
+/** Chip tone. The admin maps these four onto its own classes. */
+export type SupportTone = 'success' | 'warn' | 'danger' | 'neutral' | 'info';
+export declare function supportTicketStatusTone(status: SupportTicketStatus): SupportTone;
+export declare function supportTicketPriorityTone(priority: SupportTicketPriority): SupportTone;
+export declare function supportSlaStateTone(state: SupportSlaState): SupportTone;
+export declare function supportSyncStatusTone(status: SupportSyncStatus): SupportTone;
+export declare function customerFeedbackStatusTone(status: CustomerFeedbackStatus): SupportTone;
+export declare function customerFeedbackSentimentTone(sentiment: CustomerFeedbackSentiment): SupportTone;
+/**
+ * How a deadline reads on screen.
+ *
+ * Returns a phrase rather than a number so a paused clock does not render as a
+ * countdown that is not counting - the single most misleading thing an SLA chip
+ * can do.
+ */
+export declare function describeSupportSlaDeadline(state: SupportSlaState, remainingMinutes: number | null): string;
+/** Minutes as a short human duration: 45m, 3h 20m, 2d 4h. */
+export declare function formatSupportDuration(minutes: number | null | undefined): string;
+/**
+ * Whether an adapter can do something.
+ *
+ * The admin gates every button on this rather than assuming, so an action a
+ * helpdesk cannot perform is never offered to an operator as if it worked.
+ */
+export declare function supportProviderSupports(capabilities: SupportProviderCapability[] | null | undefined, capability: SupportProviderCapability): boolean;
+/** True for the message types a customer is allowed to see. */
+export declare function isCustomerVisibleSupportMessage(type: SupportTicketMessageType): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clarion-shared-types",
-  "version": "1.0.89",
+  "version": "1.0.91",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",