grm-shared-library 1.1.201 → 1.1.203

package/dist/esm/modules/support/utils/support-sync.util.js

@@ -0,0 +1,142 @@
+import { SUPPORT_SYNC_DEFAULTS } from '../constants/support-defaults.const';
+import { PERMANENT_SUPPORT_SYNC_FAILURE_REASONS, SupportSyncFailureReason, } from '../enums/support-sync.enum';
+/**
+ * Translate a helpdesk HTTP status into the shared failure taxonomy.
+ *
+ * The single place the retry policy is decided, because "should we call the
+ * helpdesk again?" must not be answered differently by the Zammad adapter and
+ * the Freshdesk one. Anything unrecognised is TRANSIENT: a support message that
+ * arrives late is recoverable, one dropped because an unfamiliar status looked
+ * fatal is not.
+ *
+ * The one place that reasoning inverts is a 2xx nobody could parse. The
+ * provider accepted the request, so re-sending would create a second ticket or
+ * show the customer the same reply twice - see UNREADABLE_SUCCESS, which the
+ * adapter raises directly rather than through this function.
+ */
+export function classifySupportHttpStatus(status) {
+    if (status === undefined)
+        return SupportSyncFailureReason.TIMEOUT;
+    if (status >= 200 && status < 300)
+        return SupportSyncFailureReason.UNREADABLE_SUCCESS;
+    if (status === 400 || status === 422)
+        return SupportSyncFailureReason.INVALID_PAYLOAD;
+    if (status === 401)
+        return SupportSyncFailureReason.AUTHENTICATION_FAILED;
+    if (status === 403)
+        return SupportSyncFailureReason.AUTHORIZATION_FAILED;
+    // 404 is TRANSIENT on purpose. A genuinely wrong path exhausts its attempts
+    // in a few minutes and costs nothing; a 404 from an ingress mid-deploy is
+    // common, and treating that as permanent would silently drop a reply the
+    // customer is waiting for.
+    if (status === 404)
+        return SupportSyncFailureReason.PROVIDER_UNAVAILABLE;
+    if (status === 409)
+        return SupportSyncFailureReason.PROVIDER_REJECTED;
+    if (status === 429)
+        return SupportSyncFailureReason.RATE_LIMITED;
+    if (status >= 500)
+        return SupportSyncFailureReason.PROVIDER_UNAVAILABLE;
+    if (status >= 400)
+        return SupportSyncFailureReason.PROVIDER_REJECTED;
+    return SupportSyncFailureReason.UNKNOWN;
+}
+/**
+ * Whether a failure can ever succeed on a retry.
+ *
+ * AUTHENTICATION_FAILED is deliberately NOT permanent: a rotated credential
+ * that has not propagated to every pod yet fails this way, and refusing to try
+ * again would strand every queued reply until somebody noticed. It is capped by
+ * `maxAttempts` like anything else.
+ */
+export function isPermanentSupportSyncFailure(reason) {
+    return PERMANENT_SUPPORT_SYNC_FAILURE_REASONS.includes(reason);
+}
+/**
+ * When to try again, with exponential backoff and jitter.
+ *
+ * The jitter matters more than it looks: when a helpdesk comes back after an
+ * outage, every queued row is due at once, and a synchronized stampede is how a
+ * recovering server is knocked over a second time.
+ *
+ * `randomFraction` is injected rather than read from Math.random so the
+ * function stays pure and its tests stay deterministic.
+ */
+export function computeSupportRetryDelaySeconds(attempts, options = {}) {
+    var _a, _b, _c, _d;
+    const base = (_a = options.baseSeconds) !== null && _a !== void 0 ? _a : SUPPORT_SYNC_DEFAULTS.RETRY_BASE_SECONDS;
+    const max = (_b = options.maxSeconds) !== null && _b !== void 0 ? _b : SUPPORT_SYNC_DEFAULTS.RETRY_MAX_SECONDS;
+    const jitterRatio = (_c = options.jitterRatio) !== null && _c !== void 0 ? _c : SUPPORT_SYNC_DEFAULTS.RETRY_JITTER_RATIO;
+    const randomFraction = (_d = options.randomFraction) !== null && _d !== void 0 ? _d : 0;
+    const exponent = Math.max(0, attempts - 1);
+    const raw = base * Math.pow(2, Math.min(exponent, 16));
+    let delay = Math.min(max, raw);
+    // A provider that says when to come back is obeyed, so long as it is not
+    // asking for longer than the ceiling.
+    if (options.retryAfterSeconds != null && options.retryAfterSeconds > 0) {
+        delay = Math.min(max, Math.max(delay, options.retryAfterSeconds));
+    }
+    const jitter = delay * jitterRatio * randomFraction;
+    return Math.round(delay + jitter);
+}
+/** The instant of the next attempt. */
+export function computeSupportNextAttemptAt(now, attempts, options) {
+    return new Date(now.getTime() + computeSupportRetryDelaySeconds(attempts, options) * 1000);
+}
+/**
+ * A stable fingerprint of an outbound payload.
+ *
+ * Deliberately not cryptographic. It exists to answer "is this the same request
+ * we already sent?" and to let a reconciliation job tell "never sent" from
+ * "sent and did not take" - neither of which is a security decision. Using a
+ * real digest here would pull a Node-only dependency into a package the
+ * frontend build also consumes.
+ */
+export function fingerprintSupportPayload(payload) {
+    const serialized = stableStringify(payload);
+    let hash = 5381;
+    for (let index = 0; index < serialized.length; index += 1) {
+        hash = ((hash << 5) + hash + serialized.charCodeAt(index)) | 0;
+    }
+    return `${(hash >>> 0).toString(16)}-${serialized.length.toString(16)}`;
+}
+/** JSON with object keys in a fixed order, so two equal payloads fingerprint alike. */
+function stableStringify(value) {
+    var _a;
+    if (value === null || typeof value !== 'object')
+        return (_a = JSON.stringify(value)) !== null && _a !== void 0 ? _a : 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const source = value;
+    const keys = Object.keys(source).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(source[key])}`).join(',')}}`;
+}
+/**
+ * Whether an outbound call may proceed.
+ *
+ * The breaker protects the helpdesk and this service's own worker from
+ * hammering a dead endpoint; it never causes data loss, because a call refused
+ * by an open breaker leaves its row PENDING with a CIRCUIT_OPEN reason and is
+ * retried when the breaker closes.
+ */
+export function isSupportCircuitOpen(state, now) {
+    if (!(state === null || state === void 0 ? void 0 : state.openUntil))
+        return false;
+    return new Date(state.openUntil).getTime() > now.getTime();
+}
+/** The breaker state after one outcome. */
+export function nextSupportCircuitState(state, outcome, now, options = {}) {
+    var _a, _b, _c;
+    const threshold = (_a = options.failureThreshold) !== null && _a !== void 0 ? _a : SUPPORT_SYNC_DEFAULTS.CIRCUIT_FAILURE_THRESHOLD;
+    const openSeconds = (_b = options.openSeconds) !== null && _b !== void 0 ? _b : SUPPORT_SYNC_DEFAULTS.CIRCUIT_OPEN_SECONDS;
+    if (outcome === 'success')
+        return { consecutiveFailures: 0, openUntil: null };
+    const consecutiveFailures = ((_c = state === null || state === void 0 ? void 0 : state.consecutiveFailures) !== null && _c !== void 0 ? _c : 0) + 1;
+    if (consecutiveFailures < threshold)
+        return { consecutiveFailures, openUntil: null };
+    return {
+        consecutiveFailures,
+        openUntil: new Date(now.getTime() + openSeconds * 1000).toISOString(),
+    };
+}
+//# sourceMappingURL=support-sync.util.js.map

package/dist/esm/modules/support/utils/support-sync.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-sync.util.js","sourceRoot":"","sources":["../../../../../src/modules/support/utils/support-sync.util.ts"],"names":[],"mappings":"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"}

package/dist/esm/modules/support/utils/support-ticket-number.util.js

@@ -0,0 +1,56 @@
+import { SUPPORT_TICKET_NUMBER_PREFIX, SUPPORT_TICKET_NUMBER_SEQUENCE_WIDTH, } from '../constants/support-defaults.const';
+/**
+ * Render a ticket number: SUP-KE-2026-000123.
+ *
+ * Human-readable and safe to read out over the phone, which is the whole point
+ * of it existing alongside the uuid primary key. It is never the primary key:
+ * it embeds a country and a year, and anything that embeds business meaning
+ * will eventually need changing.
+ *
+ * The sequence is allocated per (country, year) by the database, so this
+ * function only formats - it never decides what the next number is.
+ */
+export function formatSupportTicketNumber(countryCode, year, sequence) {
+    const padded = String(Math.max(0, Math.trunc(sequence))).padStart(SUPPORT_TICKET_NUMBER_SEQUENCE_WIDTH, '0');
+    return `${SUPPORT_TICKET_NUMBER_PREFIX}-${countryCode}-${year}-${padded}`;
+}
+/**
+ * Read a ticket number back, for search.
+ *
+ * Returns null rather than throwing on anything unrecognised: this runs on a
+ * search box, where the input is whatever somebody pasted, and a 500 from a bad
+ * paste is a worse answer than no results.
+ *
+ * A sequence longer than the configured width still parses - the width is a
+ * display minimum, and refusing to find ticket 1,000,000 because it has seven
+ * digits would be a bug that only appears once it is too late.
+ */
+export function parseSupportTicketNumber(value) {
+    if (value == null)
+        return null;
+    const raw = String(value).trim().toUpperCase();
+    const match = /^([A-Z]{2,5})-([A-Z]{2})-(\d{4})-(\d{1,12})$/.exec(raw);
+    if (!match)
+        return null;
+    const [, prefix, country, year, sequence] = match;
+    if (prefix !== SUPPORT_TICKET_NUMBER_PREFIX)
+        return null;
+    return {
+        prefix,
+        countryCode: country,
+        year: Number(year),
+        sequence: Number(sequence),
+    };
+}
+/**
+ * Whether a search term looks like somebody typing a ticket number.
+ *
+ * Used to route a search straight at the ticket-number index instead of running
+ * a full-text scan for a string that can only ever match one row.
+ */
+export function looksLikeSupportTicketNumber(value) {
+    if (value == null)
+        return false;
+    return /^SUP-/i.test(String(value).trim());
+}
+//# sourceMappingURL=support-ticket-number.util.js.map

package/dist/esm/modules/support/utils/support-ticket-number.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-ticket-number.util.js","sourceRoot":"","sources":["../../../../../src/modules/support/utils/support-ticket-number.util.ts"],"names":[],"mappings":"AACA,OAAO,EACH,4BAA4B,EAC5B,oCAAoC,GACvC,MAAM,qCAAqC,CAAC;AAU7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACrC,WAAwB,EACxB,IAAY,EACZ,QAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAC7D,oCAAoC,EACpC,GAAG,CACN,CAAC;IACF,OAAO,GAAG,4BAA4B,IAAI,WAAW,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAgC;IACrE,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,MAAM,KAAK,GAAG,8CAA8C,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvE,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,KAAK,CAAC;IAClD,IAAI,MAAM,KAAK,4BAA4B;QAAE,OAAO,IAAI,CAAC;IAEzD,OAAO;QACH,MAAM;QACN,WAAW,EAAE,OAAsB;QACnC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;KAC7B,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAgC;IACzE,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/C,CAAC"}

package/dist/types/index.d.ts

@@ -23,6 +23,7 @@ export * from './modules/entitlement/index';
 export * from './modules/alert-dispatch/index';
 export * from './modules/system-user/index';
 export * from './modules/partner/index';
+export * from './modules/support/index';
 export * from './interfaces/server-message';
 export * from './interfaces/i-request-with-user';
 export * from './interfaces/validated-user';

package/dist/types/kafka/topics.d.ts

@@ -55,4 +55,25 @@ export declare const KAFKA_TOPICS: {
     ORG_RESPONSE_UNIT_STATUS_CHANGED: string;
     PARTNER_DISPATCH_CREATED: string;
     PARTNER_DISPATCH_STATUS_CHANGED: string;
+    SUPPORT_TICKET_CREATED: string;
+    SUPPORT_TICKET_UPDATED: string;
+    SUPPORT_TICKET_ASSIGNED: string;
+    SUPPORT_TICKET_STATUS_CHANGED: string;
+    SUPPORT_TICKET_PRIORITY_CHANGED: string;
+    SUPPORT_TICKET_MESSAGE_CREATED: string;
+    SUPPORT_TICKET_CUSTOMER_REPLIED: string;
+    SUPPORT_TICKET_AGENT_REPLIED: string;
+    SUPPORT_TICKET_RESOLVED: string;
+    SUPPORT_TICKET_CLOSED: string;
+    SUPPORT_TICKET_REOPENED: string;
+    SUPPORT_TICKET_SLA_WARNING: string;
+    SUPPORT_TICKET_SLA_BREACHED: string;
+    SUPPORT_FEEDBACK_CREATED: string;
+    SUPPORT_FEEDBACK_UPDATED: string;
+    SUPPORT_FEEDBACK_REVIEWED: string;
+    SUPPORT_FEEDBACK_RESPONDED: string;
+    SUPPORT_FEEDBACK_CONVERTED_TO_TICKET: string;
+    SUPPORT_FEEDBACK_RATING_SUBMITTED: string;
+    SUPPORT_PROVIDER_SYNC_FAILED: string;
+    SUPPORT_PROVIDER_SYNC_RECOVERED: string;
 };

package/dist/types/modules/common/constants/service.const.d.ts

@@ -63,4 +63,8 @@ export declare const SERVICE_CONSTS: {
         name: string;
         port: number;
     };
+    SUPPORT_SERVICE: {
+        name: string;
+        port: number;
+    };
 };

package/dist/types/modules/permission/enums/permission-actions.enum.d.ts

@@ -14,6 +14,27 @@ export declare enum PermissionActions {
     RESEND_PARTNER_DISPATCH = "resend:partner-dispatch",
     READ_PARTNER_MEMBERSHIP = "read:partner-membership",
     MANAGE_PARTNER_MEMBERSHIP = "manage:partner-membership",
+    CREATE_SUPPORT_TICKET = "create:support-ticket",
+    READ_SUPPORT_TICKET = "read:support-ticket",
+    UPDATE_SUPPORT_TICKET = "update:support-ticket",
+    ASSIGN_SUPPORT_TICKET = "assign:support-ticket",
+    REPLY_SUPPORT_TICKET = "reply:support-ticket",
+    NOTE_SUPPORT_TICKET = "note:support-ticket",
+    CHANGE_STATUS_SUPPORT_TICKET = "change-status:support-ticket",
+    CHANGE_PRIORITY_SUPPORT_TICKET = "change-priority:support-ticket",
+    CLOSE_SUPPORT_TICKET = "close:support-ticket",
+    REOPEN_SUPPORT_TICKET = "reopen:support-ticket",
+    READ_SUPPORT_FEEDBACK = "read:support-feedback",
+    REVIEW_SUPPORT_FEEDBACK = "review:support-feedback",
+    RESPOND_SUPPORT_FEEDBACK = "respond:support-feedback",
+    CONVERT_SUPPORT_FEEDBACK = "convert:support-feedback",
+    MANAGE_SUPPORT_QUEUE = "manage:support-queue",
+    MANAGE_SUPPORT_TEAM = "manage:support-team",
+    MANAGE_SUPPORT_SLA = "manage:support-sla",
+    MANAGE_SUPPORT_CONFIGURATION = "manage:support-configuration",
+    READ_SUPPORT_REPORT = "read:support-report",
+    READ_SUPPORT_SYNC = "read:support-sync",
+    MANAGE_SUPPORT_SYNC = "manage:support-sync",
     CREATE_CONTROL_CENTRE = "create:control-centre",
     READ_CONTROL_CENTRE = "read:control-centre",
     UPDATE_CONTROL_CENTRE = "update:control-centre",

package/dist/types/modules/permission/enums/permissions-module.enum.d.ts

@@ -7,5 +7,6 @@ export declare enum PermissionsModule {
     INCIDENT = "Grievance",
     RESPONSE_UNIT = "Response Unit",
     BILLING = "Billing",
-    NEWSFEED = "Newsfeed"
+    NEWSFEED = "Newsfeed",
+    SUPPORT = "Support"
 }

package/dist/types/modules/socket/enums/redis-channel-name.enum.d.ts

@@ -4,5 +4,6 @@ export declare enum RedisChannelName {
     PUSH_NOTIFICATIONS = "realtime:push-notifications",
     TASKS = "realtime:tasks",
     NEWSFEED = "realtime:newsfeed",
-    TRACKING = "realtime:tracking"
+    TRACKING = "realtime:tracking",
+    SUPPORT = "realtime:support"
 }

package/dist/types/modules/socket/enums/room-type.enum.d.ts

@@ -9,5 +9,13 @@ export declare enum RoomTypeEnum {
      * like count updates.
      */
     POST = "post",
+    /**
+     * Support rooms use a two-part scheme under one prefix
+     * (support:ticket:{uuid}, support:queue:{uuid}, support:user:{id},
+     * support:org:{id}) and their own authorization, so they are matched by
+     * prefix rather than through this enum. Declared here so the prefix is
+     * registered in one place.
+     */
+    SUPPORT = "support",
     INVALID = "invalid"
 }

package/dist/types/modules/socket/enums/socket-event-name.enum.d.ts

@@ -8,5 +8,6 @@ export declare enum SocketEventName {
     TRACKING_POSITION = "tracking:position",
     TRACKING_STATUS = "tracking:status",
     TRACKING_REMOVED = "tracking:removed",
-    TRACKING_PROVIDER_HEALTH = "tracking:provider-health"
+    TRACKING_PROVIDER_HEALTH = "tracking:provider-health",
+    SUPPORT_EVENT = "support.event"
 }

package/dist/types/modules/support/constants/support-defaults.const.d.ts

@@ -0,0 +1,129 @@
+import { SupportSlaClock } from '../enums/support-sla.enum';
+import { SupportTicketPriority } from '../enums/support-ticket-priority.enum';
+/**
+ * One SLA row: how long a first response and a resolution may take, and whether
+ * the clock runs around the clock or only in working hours.
+ */
+export interface SupportSlaTargetDefaults {
+    /** Minutes allowed for the first agent reply. */
+    firstResponseMinutes: number;
+    /** Minutes allowed to reach RESOLVED. */
+    resolutionMinutes: number;
+    /**
+     * CALENDAR runs continuously; BUSINESS consumes only working minutes.
+     *
+     * The split matters at the edges. A CRITICAL ticket must be answered at 03:00
+     * on a Sunday, because an emergency platform that is down is down. A NORMAL
+     * ticket raised at 17:00 on a Friday must not be reported as breached before
+     * anybody is back at a desk - that is how a support team learns to ignore the
+     * breach column.
+     */
+    clock: SupportSlaClock;
+}
+/**
+ * The platform's default SLA matrix.
+ *
+ * These are DEFAULTS, not business rules. An organization-level policy overrides
+ * them, a queue-level policy overrides that, and both are stored data an
+ * administrator edits. Nothing in the SLA engine reads a hard-coded number.
+ *
+ * Business figures are expressed in working minutes and resolved against the
+ * country's calendar: 8 business hours = 480, 1 business day = 480, 3 business
+ * days = 1440, 5 business days = 2400.
+ */
+export declare const SUPPORT_SLA_DEFAULTS: Readonly<Record<SupportTicketPriority, SupportSlaTargetDefaults>>;
+/**
+ * The working calendar an organization inherits when it has not defined its own.
+ *
+ * Monday to Friday, 08:00-17:00 local. `timezone` is resolved from the ticket's
+ * country rather than from the server, so a Kampala ticket is measured in
+ * Kampala hours; every supported country happens to sit in the same offset
+ * today, and writing it this way is what stops that being an assumption.
+ */
+export declare const SUPPORT_BUSINESS_CALENDAR_DEFAULTS: {
+    /** ISO weekday numbers, Monday = 1. */
+    readonly workingDays: readonly number[];
+    /** Minutes past local midnight when the working day opens. */
+    readonly startMinuteOfDay: number;
+    /** Minutes past local midnight when it closes. */
+    readonly endMinuteOfDay: number;
+    /** Working minutes in one day, derived - kept here so callers need not recompute. */
+    readonly minutesPerWorkingDay: number;
+};
+/**
+ * When a ticket starts showing as WARNING rather than ON_TRACK.
+ *
+ * 80% of the way to the deadline. Expressed as a fraction rather than a fixed
+ * lead time because a fixed one is meaningless across a matrix that spans
+ * fifteen minutes to five days.
+ */
+export declare const SUPPORT_SLA_WARNING_THRESHOLD_RATIO = 0.8;
+/**
+ * How long after RESOLVED a ticket closes itself when the customer says nothing.
+ *
+ * A resolved ticket that nobody closes is invisible work: it stays out of the
+ * open counts but keeps its conversation open forever. Auto-closing is
+ * reversible - the customer can still reopen - which is why it is safe to do at
+ * all.
+ */
+export declare const SUPPORT_AUTO_CLOSE_RESOLVED_AFTER_HOURS = 72;
+/** Provider synchronization behaviour. Every value is overridable per deployment. */
+export declare const SUPPORT_SYNC_DEFAULTS: {
+    /** Attempts, including the first, before a transient failure is dead-lettered. */
+    readonly MAX_ATTEMPTS: 8;
+    /** Base of the exponential backoff, in seconds: 20s, 40s, 80s, ... */
+    readonly RETRY_BASE_SECONDS: 20;
+    /** Ceiling for the backoff, in seconds. */
+    readonly RETRY_MAX_SECONDS: 3600;
+    /** Jitter added to each retry delay, as a fraction of the delay. */
+    readonly RETRY_JITTER_RATIO: 0.2;
+    /** Per-request timeout for an outbound helpdesk call, in milliseconds. */
+    readonly REQUEST_TIMEOUT_MS: 15000;
+    /** Rows a worker claims per tick. */
+    readonly BATCH_SIZE: 25;
+    /** How long a row may sit IN_PROGRESS before it is treated as abandoned, in minutes. */
+    readonly STUCK_IN_PROGRESS_MINUTES: 10;
+    /** Consecutive provider failures that trip the circuit breaker. */
+    readonly CIRCUIT_FAILURE_THRESHOLD: 5;
+    /** How long the breaker stays open before a single probe is allowed, in seconds. */
+    readonly CIRCUIT_OPEN_SECONDS: 60;
+    /** Longest a webhook delivery record is kept for replay detection, in hours. */
+    readonly WEBHOOK_DEDUP_TTL_HOURS: 48;
+};
+/** Field limits applied before anything is sent to a helpdesk or stored. */
+export declare const SUPPORT_FIELD_LIMITS: {
+    readonly SUBJECT_MAX_LENGTH: 200;
+    readonly DESCRIPTION_MAX_LENGTH: 20000;
+    readonly MESSAGE_MAX_LENGTH: 20000;
+    readonly FEEDBACK_TITLE_MAX_LENGTH: 200;
+    readonly FEEDBACK_MESSAGE_MAX_LENGTH: 5000;
+    readonly TAG_MAX_LENGTH: 50;
+    readonly MAX_TAGS_PER_TICKET: 20;
+    readonly MAX_ATTACHMENTS_PER_MESSAGE: 10;
+    /** Longest error text persisted on a synchronization row. */
+    readonly SYNC_ERROR_MAX_LENGTH: 2000;
+    /** Longest provider payload snapshot kept on a synchronization row. */
+    readonly SYNC_SNAPSHOT_MAX_LENGTH: 8000;
+};
+/** Rating bounds for the feedback types that carry one. */
+export declare const SUPPORT_FEEDBACK_RATING: {
+    readonly MIN: 1;
+    readonly MAX: 5;
+    /** At or below this, a rating counts as negative for sentiment. */
+    readonly NEGATIVE_AT_OR_BELOW: 2;
+    /** At or above this, a rating counts as positive. */
+    readonly POSITIVE_AT_OR_ABOVE: 4;
+};
+/**
+ * Header carrying a client-supplied idempotency key.
+ *
+ * Mobile networks drop replies, not requests. Without this a customer who taps
+ * Send twice on a train raises two tickets, and the second one wastes an
+ * agent's time proving it is a duplicate of the first.
+ */
+export declare const SUPPORT_IDEMPOTENCY_HEADER = "idempotency-key";
+/** How long an idempotency key is honoured. Long enough to cover any real retry. */
+export declare const SUPPORT_IDEMPOTENCY_TTL_HOURS = 24;
+/** Ticket-number format: SUP-<COUNTRY>-<YEAR>-<6-digit sequence>. */
+export declare const SUPPORT_TICKET_NUMBER_PREFIX = "SUP";
+export declare const SUPPORT_TICKET_NUMBER_SEQUENCE_WIDTH = 6;

package/dist/types/modules/support/constants/support-kafka.const.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Consumer groups for the support topics. One group per logical consumer, so
+ * adding a consumer never steals another's messages.
+ */
+export declare const SUPPORT_CONSUMER_GROUPS: {
+    /** clarion-notification: tells a customer an agent replied, and a supervisor that an SLA slipped. */
+    readonly NOTIFICATION: "support-notification";
+    /** clarion-socket: keeps the admin console and the customer's ticket screen live. */
+    readonly REALTIME: "support-realtime";
+    /** Anything analytical that wants the raw stream. */
+    readonly ANALYTICS: "support-analytics";
+};
+/**
+ * Redis channel clarion-support publishes live ticket and feedback updates on,
+ * mirroring the newsfeed and tracking realtime bridges that clarion-socket
+ * already subscribes to.
+ *
+ * Redis rather than Kafka for the live path, deliberately: clarion-socket
+ * consumes Redis pub/sub for every other domain, and a second transport into
+ * the same service would be a new failure mode for no benefit. Kafka carries
+ * the durable, replayable record of the same facts.
+ */
+export declare const SUPPORT_REALTIME_CHANNEL = "realtime:support";
+/**
+ * Room names clients subscribe to for live support updates.
+ *
+ * A customer joins only their own ticket's room; an agent joins a queue room
+ * and their own user room. The authorization for each is enforced in
+ * clarion-socket, not here - these helpers exist so producer and consumer
+ * cannot drift on the string format.
+ */
+export declare const SUPPORT_ROOMS: {
+    readonly ticket: (ticketId: string) => string;
+    readonly queue: (queueId: string) => string;
+    readonly user: (userId: number | string) => string;
+    readonly organization: (organizationId: number | string) => string;
+};
+/**
+ * How long a consumed provider webhook is remembered, to collapse redeliveries.
+ *
+ * Helpdesks retry a delivery whose acknowledgement they did not see, and a
+ * replayed reply would be shown to the customer twice. The row is the record of
+ * record; this constant only bounds how long it is consulted.
+ */
+export declare const SUPPORT_WEBHOOK_EVENT_DEDUP_TTL_SECONDS: number;
+/** Dedup namespace used when claiming a support event id in Redis. */
+export declare const SUPPORT_EVENT_DEDUP_NAMESPACE = "support.events";

package/dist/types/modules/support/dtos/create-support-ticket-message.dto.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Add a message to a ticket conversation.
+ *
+ * There is deliberately no `type` field. Whether an entry is a customer message
+ * or an agent reply is decided by clarion-support from the caller's identity
+ * and permissions, never by the client - a customer able to post an
+ * AGENT_REPLY, or an agent able to post an internal note through the
+ * customer-facing endpoint, would each be a security bug rather than a
+ * validation one.
+ *
+ * Internal notes have their own endpoint and their own permission for the same
+ * reason.
+ */
+export declare class CreateSupportTicketMessageDto {
+    body: string;
+    documentIds?: number[];
+}
+/**
+ * Add an internal note.
+ *
+ * Never mirrored to a customer and never returned by a customer-facing
+ * endpoint. It IS pushed to the helpdesk as a note where the provider supports
+ * one, because an agent working in the helpdesk needs the same context - which
+ * is exactly why the visibility rule has to live in the domain rather than in
+ * whichever adapter happens to be configured.
+ */
+export declare class CreateSupportInternalNoteDto {
+    body: string;
+    documentIds?: number[];
+}

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

@@ -0,0 +1,35 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { IncidentAppId } from '../../incident/enums/incident-app-id.enum';
+import { SupportTicketChannel } from '../enums/support-ticket-channel.enum';
+import { SupportTicketPriority } from '../enums/support-ticket-priority.enum';
+import { SupportRelatedEntityDto } from './support-related-entity.dto';
+/**
+ * Raise a support ticket.
+ *
+ * Tenancy is NOT taken from this payload. `organizationId`, `controlCentreId`
+ * and the customer are resolved from the caller's trusted context in
+ * clarion-support; the two overridable fields below are honoured only for a
+ * super-admin or an agent raising a ticket on somebody's behalf, and are
+ * ignored for everyone else. A customer who sends another organization's id
+ * still gets a ticket in their own.
+ *
+ * Retries are safe: send the same `Idempotency-Key` header and a repeat is
+ * answered with the ticket the first attempt created. Mobile networks drop
+ * replies rather than requests, and without that a customer who taps Send twice
+ * on a train raises two tickets.
+ */
+export declare class CreateSupportTicketDto {
+    subject: string;
+    description: string;
+    categoryId?: string;
+    priority?: SupportTicketPriority;
+    channel?: SupportTicketChannel;
+    relatedEntities?: SupportRelatedEntityDto[];
+    documentIds?: number[];
+    tags?: string[];
+    appId?: IncidentAppId;
+    countryCode?: CountryCode;
+    organizationId?: number;
+    customerUserId?: number;
+    metadata?: Record<string, unknown>;
+}

package/dist/types/modules/support/dtos/customer-feedback.dto.d.ts

@@ -0,0 +1,83 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { IncidentAppId } from '../../incident/enums/incident-app-id.enum';
+import { CustomerFeedbackChannel, CustomerFeedbackSentiment, CustomerFeedbackStatus, CustomerFeedbackType } from '../enums/support-feedback.enum';
+import { SupportTicketPriority } from '../enums/support-ticket-priority.enum';
+import { SupportRelatedEntityDto } from './support-related-entity.dto';
+/**
+ * Diagnostic context a client may send with feedback.
+ *
+ * This list is a closed allowlist, not a suggestion. Anything a client sends
+ * that is not declared here is stripped by the global validation pipe, which is
+ * what stops "just send the whole failing request, it would be so useful"
+ * putting an access token in a table a wide group of people can read.
+ */
+export declare class CustomerFeedbackContextDto {
+    appId?: IncidentAppId;
+    appVersion?: string;
+    platform?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    screen?: string;
+    locale?: string;
+    correlationId?: string;
+}
+/** Submit a piece of feedback. Idempotent on the `Idempotency-Key` header, like a ticket. */
+export declare class CreateCustomerFeedbackDto {
+    type: CustomerFeedbackType;
+    title?: string;
+    message: string;
+    rating?: number;
+    channel?: CustomerFeedbackChannel;
+    relatedEntities?: SupportRelatedEntityDto[];
+    context?: CustomerFeedbackContextDto;
+    organizationId?: number;
+    countryCode?: CountryCode;
+}
+/** Reply to a customer's feedback. Moves it to RESPONDED and notifies them. */
+export declare class RespondToCustomerFeedbackDto {
+    body: string;
+}
+/** Move a piece of feedback through its review workflow. */
+export declare class UpdateCustomerFeedbackStatusDto {
+    status: CustomerFeedbackStatus;
+    reason?: string;
+    sentiment?: CustomerFeedbackSentiment;
+    tags?: string[];
+}
+/**
+ * Promote a piece of feedback into a ticket.
+ *
+ * The two records stay separate for good: the feedback keeps its own lifecycle
+ * and its own analytics, and gains a `convertedTicketId`. Merging them would
+ * lose the fact that somebody chose to escalate, which is the most interesting
+ * thing about the pair.
+ */
+export declare class ConvertFeedbackToTicketDto {
+    subject?: string;
+    priority?: SupportTicketPriority;
+    categoryId?: string;
+    queueId?: string;
+    internalNote?: string;
+}
+/** Filters for a feedback list. Narrows only; never widens the caller's scope. */
+export declare class CustomerFeedbackQueryDto {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: string;
+    sortOrder?: 'ASC' | 'DESC';
+    type?: CustomerFeedbackType;
+    status?: CustomerFeedbackStatus;
+    sentiment?: CustomerFeedbackSentiment;
+    channel?: CustomerFeedbackChannel;
+    countryCode?: CountryCode;
+    organizationId?: number;
+    appId?: IncidentAppId;
+    appVersion?: string;
+    platform?: string;
+    maxRating?: number;
+    convertedOnly?: boolean;
+    openOnly?: boolean;
+    from?: string;
+    to?: string;
+}