grm-shared-library 1.1.201 → 1.1.203

package/dist/types/modules/support/interfaces/support-events.d.ts

@@ -0,0 +1,126 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { CustomerFeedbackStatus, CustomerFeedbackType } from '../enums/support-feedback.enum';
+import { SupportProviderCode } from '../enums/support-provider-code.enum';
+import { SupportSlaState, SupportSlaTarget } from '../enums/support-sla.enum';
+import { SupportSyncFailureReason, SupportSyncOperation } from '../enums/support-sync.enum';
+import { SupportTicketMessageType } from '../enums/support-ticket-message.enum';
+import { SupportTicketPriority } from '../enums/support-ticket-priority.enum';
+import { SupportTicketStatus } from '../enums/support-ticket-status.enum';
+/**
+ * Fields every support domain event carries.
+ *
+ * Secret-free by construction: identifiers, states and timestamps only. No
+ * message body, no customer contact detail, no provider credential and no
+ * provider payload ever appears on a topic - a Kafka topic is read by consumers
+ * nobody enumerated in advance, and a support message is exactly the kind of
+ * thing that turns out to contain a password somebody pasted in.
+ *
+ * Versioned in the topic name, so a later shape change never breaks a consumer
+ * that has not been redeployed.
+ */
+export interface SupportEventEnvelopeV1 {
+    /** Deterministic where possible, so a redelivered message can be deduped. */
+    eventId: string;
+    eventType: string;
+    /** ISO-8601 instant the event was produced. */
+    occurredAt: string;
+    sourceService: 'clarion-support';
+    version: 1;
+    organizationId: number;
+    controlCentreId?: number | null;
+    countryCode: CountryCode;
+    /** Ties every event raised by one user action together. */
+    correlationId?: string | null;
+    /** Who caused it. Null for a scheduled job. */
+    actorUserId?: number | null;
+}
+/** Ticket lifecycle. Emitted for created, updated, assigned, status and priority changes. */
+export interface SupportTicketEventV1 extends SupportEventEnvelopeV1 {
+    ticketId: string;
+    ticketNumber: string;
+    /** The customer whose ticket it is - the recipient a notification consumer needs. */
+    customerUserId: number;
+    status: SupportTicketStatus;
+    previousStatus?: SupportTicketStatus | null;
+    priority: SupportTicketPriority;
+    previousPriority?: SupportTicketPriority | null;
+    categoryId?: string | null;
+    queueId?: string | null;
+    assignedAgentId?: number | null;
+    previousAssignedAgentId?: number | null;
+    assignedTeamId?: string | null;
+    /**
+     * The subject line.
+     *
+     * The one piece of customer-authored text on a topic, and it is here because
+     * a notification that cannot say which ticket it is about is useless. It is
+     * the same string already shown in a list; the body never travels.
+     */
+    subject: string;
+    externalProvider?: SupportProviderCode | null;
+    externalTicketId?: string | null;
+}
+/** A new entry in a ticket conversation. */
+export interface SupportTicketMessageEventV1 extends SupportEventEnvelopeV1 {
+    ticketId: string;
+    ticketNumber: string;
+    customerUserId: number;
+    messageId: string;
+    messageType: SupportTicketMessageType;
+    authorUserId?: number | null;
+    /** Length only. The body itself is deliberately absent. */
+    bodyLength: number;
+    hasAttachments: boolean;
+    /** Who should be told: the customer for an agent reply, the agent for a customer reply. */
+    assignedAgentId?: number | null;
+    queueId?: string | null;
+    subject: string;
+    /** False for an internal note, which no customer-facing consumer may act on. */
+    customerVisible: boolean;
+}
+/** An SLA clock crossing a threshold. */
+export interface SupportSlaEventV1 extends SupportEventEnvelopeV1 {
+    ticketId: string;
+    ticketNumber: string;
+    subject: string;
+    target: SupportSlaTarget;
+    state: SupportSlaState;
+    dueAt: string;
+    /** Negative before the deadline, positive after it. */
+    overdueMinutes: number;
+    priority: SupportTicketPriority;
+    assignedAgentId?: number | null;
+    assignedTeamId?: string | null;
+    queueId?: string | null;
+    /** Who should hear about it - supervisors first, then managers. */
+    escalationUserIds: number[];
+}
+/** Customer feedback lifecycle. */
+export interface SupportFeedbackEventV1 extends SupportEventEnvelopeV1 {
+    feedbackId: string;
+    submittedByUserId: number;
+    type: CustomerFeedbackType;
+    status: CustomerFeedbackStatus;
+    previousStatus?: CustomerFeedbackStatus | null;
+    rating?: number | null;
+    /** Set on the converted event. */
+    convertedTicketId?: string | null;
+    convertedTicketNumber?: string | null;
+}
+/**
+ * Provider synchronization health.
+ *
+ * Emitted when a row is dead-lettered and again when the provider recovers, so
+ * an operations dashboard can show a helpdesk outage without polling and
+ * without reading the support database.
+ */
+export interface SupportProviderSyncEventV1 extends SupportEventEnvelopeV1 {
+    provider: SupportProviderCode;
+    syncId: string;
+    ticketId?: string | null;
+    operation: SupportSyncOperation;
+    failureReason?: SupportSyncFailureReason | null;
+    attempts: number;
+    /** How many rows are currently dead-lettered for this provider. */
+    deadLetterCount: number;
+}

package/dist/types/modules/support/interfaces/support-provider-descriptor.d.ts

@@ -0,0 +1,92 @@
+import { SupportProviderCapability, SupportProviderCode } from '../enums/support-provider-code.enum';
+/** One non-secret setting an adapter needs, described so a UI can render it. */
+export interface SupportProviderConfigField {
+    /** Key in the integration's `configuration` object. */
+    key: string;
+    label: string;
+    description?: string | null;
+    type: 'string' | 'number' | 'boolean' | 'select';
+    required: boolean;
+    /** Options when `type` is select. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** Shown as a placeholder. Never a real value. */
+    example?: string | null;
+    defaultValue?: string | number | boolean | null;
+}
+/**
+ * A credential the adapter needs, described by NAME only.
+ *
+ * The admin renders a field for the credential's REFERENCE - the name of a
+ * secret in the deployment's secret store - and never for the credential
+ * itself. There is no code path anywhere in the platform that accepts a
+ * helpdesk API token over HTTP, which is the point: a token typed into a
+ * browser is a token in a browser history, a proxy log and an admin's
+ * clipboard.
+ */
+export interface SupportProviderCredentialField {
+    key: string;
+    label: string;
+    description?: string | null;
+    required: boolean;
+}
+/**
+ * Everything the platform can say about one helpdesk without contacting it.
+ *
+ * The admin builds its configuration form and its action buttons from this, so
+ * adding a provider is a backend change with no frontend change - and an action
+ * a provider cannot perform is never offered to an operator as if it worked.
+ */
+export interface SupportProviderDescriptor {
+    code: SupportProviderCode;
+    /** Operator-facing name, e.g. Zammad. */
+    name: string;
+    description: string;
+    /** What this adapter can actually do. */
+    capabilities: SupportProviderCapability[];
+    /** Hostnames a base URL may point at, beyond the deployment allowlist. Empty means self-hosted. */
+    allowedHosts: string[];
+    /** True when the deployment can reach this provider - credential present and adapter enabled. */
+    available: boolean;
+    /** Why it is unavailable, when it is. Never contains a secret. */
+    unavailableReason?: string | null;
+    configFields: SupportProviderConfigField[];
+    credentialFields: SupportProviderCredentialField[];
+    /** True when the provider signs its webhooks and Clarion verifies the signature. */
+    verifiesWebhookSignature: boolean;
+    /** Path the provider should be configured to call, relative to the public API host. */
+    webhookPath?: string | null;
+}
+/** The outcome of an operator pressing Test Connection. Never carries a credential. */
+export interface SupportProviderConnectionTestResult {
+    provider: SupportProviderCode;
+    success: boolean;
+    /** Human-readable, already scrubbed of anything credential-shaped. */
+    message: string;
+    latencyMs?: number | null;
+    checkedAt: string;
+}
+/**
+ * The provider a deployment is running, as the admin sees it.
+ *
+ * Configuration-driven and read-only over the API: switching provider is a
+ * deployment decision made with an environment variable and a documented
+ * migration procedure, not a button. A screen that let somebody flip the
+ * platform's helpdesk in one click would be a screen that orphans every open
+ * ticket.
+ */
+export interface SupportProviderStatus {
+    /** What SUPPORT_PROVIDER resolves to right now. */
+    activeProvider: SupportProviderCode;
+    /** Every adapter the build carries, whether or not it is configured. */
+    providers: SupportProviderDescriptor[];
+    /** Outstanding synchronization work, as a health signal. */
+    pendingSyncCount: number;
+    deadLetterSyncCount: number;
+    /** True while the circuit breaker is open for the active provider. */
+    circuitOpen: boolean;
+    lastSuccessfulSyncAt?: string | null;
+    lastFailedSyncAt?: string | null;
+}

package/dist/types/modules/support/interfaces/support-realtime.d.ts

@@ -0,0 +1,65 @@
+import { SupportSlaState } from '../enums/support-sla.enum';
+import { SupportTicketMessageType } from '../enums/support-ticket-message.enum';
+import { SupportTicketPriority } from '../enums/support-ticket-priority.enum';
+import { SupportTicketStatus } from '../enums/support-ticket-status.enum';
+/** What a live support update is about. */
+export declare enum SupportRealtimeEventType {
+    TICKET_CREATED = "support.ticket.created",
+    TICKET_UPDATED = "support.ticket.updated",
+    TICKET_STATUS_CHANGED = "support.ticket.status.changed",
+    TICKET_PRIORITY_CHANGED = "support.ticket.priority.changed",
+    TICKET_ASSIGNED = "support.ticket.assigned",
+    TICKET_MESSAGE_CREATED = "support.ticket.message.created",
+    TICKET_SLA_CHANGED = "support.ticket.sla.changed",
+    TICKET_SYNC_CHANGED = "support.ticket.sync.changed",
+    FEEDBACK_CREATED = "support.feedback.created",
+    FEEDBACK_RESPONDED = "support.feedback.responded"
+}
+/**
+ * The flat envelope clarion-support publishes on the support Redis channel and
+ * clarion-socket re-broadcasts to rooms.
+ *
+ * Flat rather than the rich incident `EventEnvelope<T>` for the same reason
+ * newsfeed and tracking are: support events span tickets, messages and
+ * feedback, and forcing three unrelated payload shapes through one generic
+ * costs more than it buys.
+ *
+ * The payload is CLIENT-SAFE and minimal - enough to update a row or append a
+ * bubble, never enough to be an unauthorized read. In particular an internal
+ * note is broadcast ONLY to the queue and agent rooms and never to the
+ * customer's ticket room, 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 SupportRealtimeEnvelope {
+    eventId: string;
+    eventType: SupportRealtimeEventType;
+    occurredAt: string;
+    organizationId: number;
+    controlCentreId?: number | null;
+    /** Rooms clarion-socket should deliver to. Built with SUPPORT_ROOMS. */
+    rooms: string[];
+    ticketId?: string;
+    ticketNumber?: string;
+    feedbackId?: string;
+    actorUserId?: number | null;
+    payload: SupportRealtimePayload;
+}
+/** The client-safe body of a live support update. */
+export interface SupportRealtimePayload {
+    status?: SupportTicketStatus;
+    previousStatus?: SupportTicketStatus | null;
+    priority?: SupportTicketPriority;
+    assignedAgentId?: number | null;
+    queueId?: string | null;
+    messageId?: string;
+    messageType?: SupportTicketMessageType;
+    /** Whether the new message is one the customer may see. */
+    customerVisible?: boolean;
+    authorName?: string | null;
+    firstResponseSlaState?: SupportSlaState;
+    resolutionSlaState?: SupportSlaState;
+    externalSyncPending?: boolean;
+    externalSyncFailed?: boolean;
+    /** Server time the ticket last changed, so a client can discard a stale update. */
+    updatedAt?: string;
+}

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

@@ -0,0 +1,122 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { CustomerFeedbackStatus, CustomerFeedbackType } from '../enums/support-feedback.enum';
+import { SupportTicketChannel } from '../enums/support-ticket-channel.enum';
+import { SupportTicketPriority } from '../enums/support-ticket-priority.enum';
+import { SupportTicketStatus } from '../enums/support-ticket-status.enum';
+/** A count against a dimension value. The shape every breakdown uses. */
+export interface SupportMetricBucket {
+    key: string;
+    /** Display label resolved server-side, so a client never has to own a label map. */
+    label: string;
+    count: number;
+}
+/** A count at a point in time, for the trend charts. */
+export interface SupportTimeSeriesPoint {
+    /** Bucket start, ISO-8601. */
+    at: string;
+    count: number;
+}
+/**
+ * The support overview.
+ *
+ * Every number is scoped to the caller's tenant and to the requested date
+ * range. Averages 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 SupportDashboardMetrics {
+    /** Range the figures cover. */
+    from: string;
+    to: string;
+    totalTickets: number;
+    newTickets: number;
+    openTickets: number;
+    resolvedTickets: number;
+    closedTickets: number;
+    unassignedTickets: number;
+    /** Open tickets with at least one breached clock. */
+    breachedTickets: number;
+    /** Open tickets in WARNING on either clock. */
+    atRiskTickets: number;
+    byStatus: SupportMetricBucket[];
+    byPriority: SupportMetricBucket[];
+    byChannel: SupportMetricBucket[];
+    byCategory: SupportMetricBucket[];
+    byQueue: SupportMetricBucket[];
+    byCountry: SupportMetricBucket[];
+    /** Only populated for a super-admin, who is the only caller who spans tenants. */
+    byOrganization: SupportMetricBucket[];
+    /** Percentage of tickets in range that met their first-response target. */
+    firstResponseComplianceRate: number;
+    /** Percentage that met their resolution target. */
+    resolutionComplianceRate: number;
+    slaBreachCount: number;
+    averageFirstResponseMinutes?: number | null;
+    averageResolutionMinutes?: number | null;
+    /** Reopened tickets as a percentage of tickets closed in range. */
+    reopenRate: number;
+    feedbackCount: number;
+    averageRating?: number | null;
+    feedbackByType: SupportMetricBucket[];
+    /** Percentage of feedback that received a reply. */
+    feedbackResponseRate: number;
+    /** Percentage of feedback that became a ticket. */
+    feedbackConversionRate: number;
+    ticketsCreatedTrend: SupportTimeSeriesPoint[];
+    ticketsResolvedTrend: SupportTimeSeriesPoint[];
+}
+/** One agent's board. */
+export interface SupportAgentDashboardMetrics {
+    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;
+    /** Tickets 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 SupportFeedbackAnalytics {
+    from: string;
+    to: string;
+    total: number;
+    byType: SupportMetricBucket[];
+    byStatus: SupportMetricBucket[];
+    byCountry: SupportMetricBucket[];
+    byOrganization: SupportMetricBucket[];
+    byApp: SupportMetricBucket[];
+    byAppVersion: SupportMetricBucket[];
+    byPlatform: SupportMetricBucket[];
+    bySentiment: SupportMetricBucket[];
+    averageRating?: number | null;
+    ratingDistribution: SupportMetricBucket[];
+    responseRate: number;
+    conversionRate: number;
+    volumeTrend: SupportTimeSeriesPoint[];
+}
+/** Filters every report endpoint accepts. */
+export interface SupportReportQuery {
+    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;
+    /** Bucket size for the trend series. */
+    granularity?: 'DAY' | 'WEEK' | 'MONTH';
+}

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

@@ -0,0 +1,105 @@
+import { SupportProviderCode } from '../enums/support-provider-code.enum';
+import { SupportSyncEntityType, SupportSyncFailureReason, SupportSyncOperation, SupportSyncStatus, SupportWebhookStatus } from '../enums/support-sync.enum';
+/**
+ * One unit of outbound work against a helpdesk.
+ *
+ * This row IS the queue. There is no broker behind it: a PENDING row whose
+ * `nextAttemptAt` has elapsed is work, claimed with SELECT ... FOR UPDATE SKIP
+ * LOCKED, so an operation survives a pod dying mid-send with nothing to replay
+ * from. Nothing is ever silently discarded - a row that cannot succeed becomes
+ * DEAD_LETTER and shows up on the synchronization dashboard for a human.
+ */
+export interface SupportProviderSync {
+    id: string;
+    organizationId: number;
+    provider: SupportProviderCode;
+    entityType: SupportSyncEntityType;
+    /** The Clarion id of the record being mirrored. */
+    entityId: string;
+    /** The ticket the work belongs to, for grouping on the dashboard. */
+    ticketId?: string | null;
+    /** The provider's id, once known. */
+    externalId?: string | null;
+    operation: SupportSyncOperation;
+    status: SupportSyncStatus;
+    attempts: number;
+    maxAttempts: number;
+    lastAttemptAt?: string | null;
+    nextAttemptAt?: string | null;
+    failureReason?: SupportSyncFailureReason | null;
+    /** The provider's own error code, when it publishes one. */
+    errorCode?: string | null;
+    /** Scrubbed and length-capped. Safe to show an operator. */
+    errorMessage?: string | null;
+    /**
+     * Hash of the payload that was sent.
+     *
+     * Two purposes. It lets a redelivery be recognised without keeping the
+     * payload, and it lets a reconciliation job tell "we never sent this" from
+     * "we sent this and it did not take".
+     */
+    payloadHash?: string | null;
+    /** Ties every row raised by one user action together. */
+    correlationId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A synchronization row plus the small amount of context the dashboard shows. */
+export interface SupportProviderSyncSummary extends SupportProviderSync {
+    ticketNumber?: string | null;
+    /** How long the row has been outstanding, in minutes. */
+    ageMinutes: number;
+}
+/**
+ * A webhook delivery from a helpdesk.
+ *
+ * Persisted BEFORE it is processed, and keyed on the provider's delivery id, so
+ * a replay is recognised as a replay rather than shown to a customer twice. A
+ * delivery whose signature does not verify is recorded as REJECTED and never
+ * processed, because knowing somebody is posting unsigned traffic at the
+ * endpoint is worth more than the disk it costs.
+ */
+export interface SupportWebhookEvent {
+    id: string;
+    provider: SupportProviderCode;
+    /** The provider's delivery id when it sends one; otherwise a hash of the body. */
+    externalEventId: string;
+    /** The provider's own event name, unmapped, for diagnosis. */
+    externalEventType?: string | null;
+    /** The Clarion ticket it resolved to, when it resolved to one. */
+    ticketId?: string | null;
+    externalTicketId?: string | null;
+    status: SupportWebhookStatus;
+    /** Why it was ignored or rejected. Never contains the signature or a secret. */
+    statusReason?: string | null;
+    receivedAt: string;
+    processedAt?: string | null;
+    /** How long processing took, for the latency panel. */
+    durationMs?: number | null;
+}
+/**
+ * The result of reconciling one ticket against the provider.
+ *
+ * Reconciliation never guesses. Where the two disagree on workflow state the
+ * provider wins, because that is where agents work; where they disagree on
+ * tenancy, identity or the customer's own messages Clarion wins, because the
+ * provider has no authority over those. Anything it cannot place is reported
+ * rather than resolved.
+ */
+export interface SupportReconciliationResult {
+    ticketId: string;
+    ticketNumber: string;
+    provider: SupportProviderCode;
+    externalTicketId?: string | null;
+    /** True when the two copies already agreed. */
+    inSync: boolean;
+    /** Field-level differences found, e.g. `status`. */
+    differences: string[];
+    /** Changes actually applied to the Clarion copy. */
+    applied: string[];
+    /** Differences left alone for a human, with the reason. */
+    unresolved: string[];
+    /** Messages pulled in from the provider that Clarion had never seen. */
+    messagesImported: number;
+    reconciledAt: string;
+}

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

@@ -0,0 +1,66 @@
+import { SupportProviderCode } from '../enums/support-provider-code.enum';
+import { SupportMessageAuthorType, SupportMessageOrigin, SupportTicketMessageType } from '../enums/support-ticket-message.enum';
+/**
+ * A file attached to a ticket or a message.
+ *
+ * The bytes live in clarion-dms and nowhere else. What is stored here is a
+ * reference plus the metadata needed to render a list without fetching
+ * anything. `downloadUrl` is minted per request through Clarion after an
+ * authorization check - a provider's own attachment URL is never handed to a
+ * client, because those URLs are frequently unauthenticated and permanent.
+ */
+export interface SupportTicketAttachment {
+    id: string;
+    ticketId: string;
+    /** Null for an attachment added to the ticket rather than to one message. */
+    messageId?: string | null;
+    /** The clarion-dms document id. The only durable pointer to the bytes. */
+    documentId: number;
+    fileName: string;
+    mimeType: string;
+    sizeBytes: number;
+    uploadedByUserId?: number | null;
+    /** True when the file arrived from the helpdesk rather than from a Clarion client. */
+    fromProvider: boolean;
+    /** The provider's id for the same file, when it has one. */
+    externalAttachmentId?: string | null;
+    /**
+     * Short-lived, authorization-checked URL. Present only on a single-ticket
+     * read, never on a list, and never persisted.
+     */
+    downloadUrl?: string | null;
+    createdAt: string;
+}
+/**
+ * One entry in a ticket conversation.
+ *
+ * Persisted in Clarion even when a helpdesk is the operational source of truth,
+ * because the local copy is what makes the customer's screen work during a
+ * provider outage, what makes analytics possible, and what makes a change of
+ * provider a migration rather than a data loss.
+ */
+export interface SupportTicketMessage {
+    id: string;
+    ticketId: string;
+    type: SupportTicketMessageType;
+    authorType: SupportMessageAuthorType;
+    /** Null for a system message, or for an agent who exists only in the helpdesk. */
+    authorUserId?: number | null;
+    /** Display name resolved at read time. For a provider agent, the name the provider gave. */
+    authorName?: string | null;
+    body: string;
+    /** Whether the entry was written here or arrived from the helpdesk. */
+    origin: SupportMessageOrigin;
+    externalProvider?: SupportProviderCode | null;
+    externalMessageId?: string | null;
+    attachments: SupportTicketAttachment[];
+    /**
+     * True once the message has been mirrored to the helpdesk, or when it never
+     * needed to be. A client shows an in-flight reply differently, rather than
+     * pretending a queued message has been delivered.
+     */
+    externalSyncPending: boolean;
+    /** Structured detail for a STATUS_MESSAGE, e.g. the two statuses involved. */
+    metadata?: Record<string, unknown> | null;
+    createdAt: string;
+}