@consilioweb/payload-support 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -381,6 +381,87 @@ declare const DEFAULT_SLUGS: CollectionSlugs;
  */
 declare function resolveSlugs(overrides?: Partial<CollectionSlugs>): CollectionSlugs;
 
+/**
+ * Ticketing feature flags — single source of truth (client + server).
+ *
+ * Flags are stored SERVER-side, in the `support-settings` row of
+ * `payload-preferences` (see `readSettings.ts` and `endpoints/settings.ts`).
+ * A flag toggled on one machine therefore applies to every browser and to
+ * server-side code (hooks, cron endpoints) alike.
+ *
+ * `localStorage` is still used, but demoted to a plain CACHE: it lets admin
+ * views paint synchronously on first render and keeps them usable when the
+ * settings endpoint is unreachable. It is never authoritative.
+ *
+ * Two flags are *projections* of settings that already lived server-side long
+ * before this module, and are deliberately NOT stored twice:
+ *   - `autoClose`     ← `settings.autoClose.enabled`
+ *   - `autoCloseDays` ← `settings.autoClose.daysBeforeClose`
+ * The `autoClose` block stays authoritative; the flags are recomputed on read
+ * and dropped on write. See `projectAutoClose` / `stripProjectedFeatures`.
+ */
+/**
+ * Feature flags for the ticketing module.
+ * Each feature can be enabled/disabled by the admin.
+ * When disabled, the corresponding UI section is hidden entirely.
+ */
+interface TicketingFeatures {
+    /** Time tracking: timer, manual entries, billing */
+    timeTracking: boolean;
+    /** AI features: sentiment, synthesis, suggestion, rewrite */
+    ai: boolean;
+    /** Satisfaction surveys: CSAT rating after resolution */
+    satisfaction: boolean;
+    /** Live chat integration: chat → ticket conversion */
+    chat: boolean;
+    /** Email tracking: pixel tracking, open/sent status per message */
+    emailTracking: boolean;
+    /** Canned responses: quick reply templates */
+    canned: boolean;
+    /** Ticket merge: combine two tickets into one */
+    merge: boolean;
+    /** Snooze: temporarily hide a ticket */
+    snooze: boolean;
+    /** External messages: add messages received outside the system */
+    externalMessages: boolean;
+    /** Client history: past tickets, projects, notes sidebar */
+    clientHistory: boolean;
+    /** Activity log: audit trail of actions on the ticket */
+    activityLog: boolean;
+    /** Split ticket: extract a message into a new ticket */
+    splitTicket: boolean;
+    /** Scheduled replies: send a message at a future date */
+    scheduledReplies: boolean;
+    /** Auto-close: automatically resolve inactive tickets (projection of settings.autoClose.enabled) */
+    autoClose: boolean;
+    /** Auto-close delay in days (projection of settings.autoClose.daysBeforeClose) */
+    autoCloseDays: number;
+    /** Round-robin: distribute new tickets evenly among agents */
+    roundRobin: boolean;
+}
+/** Default features — all enabled except round-robin */
+declare const DEFAULT_TICKETING_FEATURES: TicketingFeatures;
+/** Flags derived from another settings block — never persisted inside `features`. */
+declare const PROJECTED_FEATURE_KEYS: readonly ["autoClose", "autoCloseDays"];
+/**
+ * Coerce arbitrary input (stale localStorage, hand-edited preference row, older
+ * plugin version) into a complete, well-typed feature set. Unknown keys are
+ * dropped and wrongly-typed values fall back to their default.
+ */
+declare function normalizeFeatures(raw: unknown): TicketingFeatures;
+/** Shape of the `autoClose` settings block the two projected flags mirror. */
+interface AutoCloseProjectionSource {
+    enabled?: boolean;
+    daysBeforeClose?: number;
+}
+/** Recompute the projected flags from the authoritative `autoClose` block. */
+declare function projectAutoClose(features: TicketingFeatures, autoClose: AutoCloseProjectionSource | undefined): TicketingFeatures;
+/**
+ * Drop the projected flags before persisting, so `features` and the `autoClose`
+ * block can never disagree.
+ */
+declare function stripProjectedFeatures(features: TicketingFeatures): Omit<TicketingFeatures, (typeof PROJECTED_FEATURE_KEYS)[number]>;
+
 interface SupportSettings {
     email: {
         fromAddress: string;
@@ -406,6 +487,8 @@ interface SupportSettings {
         daysBeforeClose: number;
         reminderDaysBefore: number;
     };
+    /** Ticketing feature flags — server-authoritative since 2.1 (used to be per-browser localStorage). */
+    features: TicketingFeatures;
 }
 interface UserPrefs {
     locale: 'fr' | 'en';
@@ -413,6 +496,16 @@ interface UserPrefs {
 }
 declare const DEFAULT_SETTINGS: SupportSettings;
 declare const DEFAULT_USER_PREFS: UserPrefs;
+interface SupportSettingsState {
+    settings: SupportSettings;
+    /**
+     * False when the preference row carries no `features` object yet — a
+     * pre-2.1 install, or a fresh one. Clients use it to decide whether their
+     * legacy `localStorage` flags should seed the server.
+     */
+    featuresConfigured: boolean;
+}
+declare function readSupportSettingsState(payload: Payload): Promise<SupportSettingsState>;
 declare function readSupportSettings(payload: Payload): Promise<SupportSettings>;
 declare function readUserPrefs(payload: Payload, userId: string | number): Promise<UserPrefs>;
 
@@ -455,7 +548,11 @@ declare function createAdminNotification(payload: Payload, data: {
     recipient?: number | string;
 }, collectionSlug?: string): Promise<void>;
 
-type WebhookEvent = 'ticket_created' | 'ticket_resolved' | 'ticket_replied' | 'sla_breached';
+/**
+ * Outbound webhook events. Must stay in sync with the `events` options of the
+ * webhook-endpoints collection.
+ */
+type WebhookEvent = 'ticket_created' | 'ticket_resolved' | 'ticket_replied' | 'ticket_assigned' | 'sla_breached';
 /**
  * Dispatch outbound webhooks for a given event.
  * Fetches all active webhook endpoints matching the event,
@@ -467,7 +564,7 @@ type WebhookEvent = 'ticket_created' | 'ticket_resolved' | 'ticket_replied' | 's
  * @param payload - Payload instance
  * @param slugs - Collection slugs for dynamic collection references
  */
-declare function dispatchWebhook(data: Record<string, unknown>, event: WebhookEvent, payload: BasePayload, slugs: CollectionSlugs): void;
+declare function dispatchWebhook(data: Record<string, unknown>, event: WebhookEvent, payload: BasePayload, slugs: CollectionSlugs): Promise<void>;
 
 interface TicketSynthesisResult {
     summary: string;
@@ -578,4 +675,4 @@ declare function createTicketStatusesCollection(slugs: CollectionSlugs): Collect
  */
 declare function createTicketCollaboratorsCollection(slugs: CollectionSlugs): CollectionConfig;
 
-export { type AIProviderConfig, type ActivityEntryData, type CannedResponseData, type ClientData, type CollectionSlugs, DEFAULT_FEATURES, DEFAULT_INBOUND_EMAIL_LIMITS, DEFAULT_SETTINGS, DEFAULT_SLUGS, DEFAULT_USER_PREFS, type EmailConfig, type InboundEmailInput, type InboundEmailLimits, type InboundEmailValidationError, MemoryRateLimitStore, type MessageData, PayloadRateLimitStore, type RateLimitEntry, type RateLimitStore, RateLimiter, type SatisfactionSurveyData, type SupportFeatures, type SupportPluginConfig, type SupportSettings, type TicketData, type TicketSynthesisResult, type TimeEntryData, type UserPrefs, calculateBusinessHoursDeadline, createAdminNotification, createAssignSlaDeadlines, createAuthLogsCollection, createCannedResponsesCollection, createChatMessagesCollection, createCheckSlaOnReply, createCheckSlaOnResolve, createEmailLogsCollection, createKnowledgeBaseCollection, createLoginEndpoint, createMacrosCollection, createOAuthGoogleEndpoint, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createTrackOpenEndpoint, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, readSupportSettings, readUserPrefs, resolveSlugs, supportPlugin, validateInboundEmailPayload, verifySecret };
+export { type AIProviderConfig, type ActivityEntryData, type CannedResponseData, type ClientData, type CollectionSlugs, DEFAULT_FEATURES, DEFAULT_INBOUND_EMAIL_LIMITS, DEFAULT_SETTINGS, DEFAULT_SLUGS, DEFAULT_TICKETING_FEATURES, DEFAULT_USER_PREFS, type EmailConfig, type InboundEmailInput, type InboundEmailLimits, type InboundEmailValidationError, MemoryRateLimitStore, type MessageData, PayloadRateLimitStore, type RateLimitEntry, type RateLimitStore, RateLimiter, type SatisfactionSurveyData, type SupportFeatures, type SupportPluginConfig, type SupportSettings, type SupportSettingsState, type TicketData, type TicketSynthesisResult, type TicketingFeatures, type TimeEntryData, type UserPrefs, calculateBusinessHoursDeadline, createAdminNotification, createAssignSlaDeadlines, createAuthLogsCollection, createCannedResponsesCollection, createChatMessagesCollection, createCheckSlaOnReply, createCheckSlaOnResolve, createEmailLogsCollection, createKnowledgeBaseCollection, createLoginEndpoint, createMacrosCollection, createOAuthGoogleEndpoint, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createTrackOpenEndpoint, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, normalizeFeatures, projectAutoClose, readSupportSettings, readSupportSettingsState, readUserPrefs, resolveSlugs, stripProjectedFeatures, supportPlugin, validateInboundEmailPayload, verifySecret };

package/dist/index.d.ts

@@ -381,6 +381,87 @@ declare const DEFAULT_SLUGS: CollectionSlugs;
  */
 declare function resolveSlugs(overrides?: Partial<CollectionSlugs>): CollectionSlugs;
 
+/**
+ * Ticketing feature flags — single source of truth (client + server).
+ *
+ * Flags are stored SERVER-side, in the `support-settings` row of
+ * `payload-preferences` (see `readSettings.ts` and `endpoints/settings.ts`).
+ * A flag toggled on one machine therefore applies to every browser and to
+ * server-side code (hooks, cron endpoints) alike.
+ *
+ * `localStorage` is still used, but demoted to a plain CACHE: it lets admin
+ * views paint synchronously on first render and keeps them usable when the
+ * settings endpoint is unreachable. It is never authoritative.
+ *
+ * Two flags are *projections* of settings that already lived server-side long
+ * before this module, and are deliberately NOT stored twice:
+ *   - `autoClose`     ← `settings.autoClose.enabled`
+ *   - `autoCloseDays` ← `settings.autoClose.daysBeforeClose`
+ * The `autoClose` block stays authoritative; the flags are recomputed on read
+ * and dropped on write. See `projectAutoClose` / `stripProjectedFeatures`.
+ */
+/**
+ * Feature flags for the ticketing module.
+ * Each feature can be enabled/disabled by the admin.
+ * When disabled, the corresponding UI section is hidden entirely.
+ */
+interface TicketingFeatures {
+    /** Time tracking: timer, manual entries, billing */
+    timeTracking: boolean;
+    /** AI features: sentiment, synthesis, suggestion, rewrite */
+    ai: boolean;
+    /** Satisfaction surveys: CSAT rating after resolution */
+    satisfaction: boolean;
+    /** Live chat integration: chat → ticket conversion */
+    chat: boolean;
+    /** Email tracking: pixel tracking, open/sent status per message */
+    emailTracking: boolean;
+    /** Canned responses: quick reply templates */
+    canned: boolean;
+    /** Ticket merge: combine two tickets into one */
+    merge: boolean;
+    /** Snooze: temporarily hide a ticket */
+    snooze: boolean;
+    /** External messages: add messages received outside the system */
+    externalMessages: boolean;
+    /** Client history: past tickets, projects, notes sidebar */
+    clientHistory: boolean;
+    /** Activity log: audit trail of actions on the ticket */
+    activityLog: boolean;
+    /** Split ticket: extract a message into a new ticket */
+    splitTicket: boolean;
+    /** Scheduled replies: send a message at a future date */
+    scheduledReplies: boolean;
+    /** Auto-close: automatically resolve inactive tickets (projection of settings.autoClose.enabled) */
+    autoClose: boolean;
+    /** Auto-close delay in days (projection of settings.autoClose.daysBeforeClose) */
+    autoCloseDays: number;
+    /** Round-robin: distribute new tickets evenly among agents */
+    roundRobin: boolean;
+}
+/** Default features — all enabled except round-robin */
+declare const DEFAULT_TICKETING_FEATURES: TicketingFeatures;
+/** Flags derived from another settings block — never persisted inside `features`. */
+declare const PROJECTED_FEATURE_KEYS: readonly ["autoClose", "autoCloseDays"];
+/**
+ * Coerce arbitrary input (stale localStorage, hand-edited preference row, older
+ * plugin version) into a complete, well-typed feature set. Unknown keys are
+ * dropped and wrongly-typed values fall back to their default.
+ */
+declare function normalizeFeatures(raw: unknown): TicketingFeatures;
+/** Shape of the `autoClose` settings block the two projected flags mirror. */
+interface AutoCloseProjectionSource {
+    enabled?: boolean;
+    daysBeforeClose?: number;
+}
+/** Recompute the projected flags from the authoritative `autoClose` block. */
+declare function projectAutoClose(features: TicketingFeatures, autoClose: AutoCloseProjectionSource | undefined): TicketingFeatures;
+/**
+ * Drop the projected flags before persisting, so `features` and the `autoClose`
+ * block can never disagree.
+ */
+declare function stripProjectedFeatures(features: TicketingFeatures): Omit<TicketingFeatures, (typeof PROJECTED_FEATURE_KEYS)[number]>;
+
 interface SupportSettings {
     email: {
         fromAddress: string;
@@ -406,6 +487,8 @@ interface SupportSettings {
         daysBeforeClose: number;
         reminderDaysBefore: number;
     };
+    /** Ticketing feature flags — server-authoritative since 2.1 (used to be per-browser localStorage). */
+    features: TicketingFeatures;
 }
 interface UserPrefs {
     locale: 'fr' | 'en';
@@ -413,6 +496,16 @@ interface UserPrefs {
 }
 declare const DEFAULT_SETTINGS: SupportSettings;
 declare const DEFAULT_USER_PREFS: UserPrefs;
+interface SupportSettingsState {
+    settings: SupportSettings;
+    /**
+     * False when the preference row carries no `features` object yet — a
+     * pre-2.1 install, or a fresh one. Clients use it to decide whether their
+     * legacy `localStorage` flags should seed the server.
+     */
+    featuresConfigured: boolean;
+}
+declare function readSupportSettingsState(payload: Payload): Promise<SupportSettingsState>;
 declare function readSupportSettings(payload: Payload): Promise<SupportSettings>;
 declare function readUserPrefs(payload: Payload, userId: string | number): Promise<UserPrefs>;
 
@@ -455,7 +548,11 @@ declare function createAdminNotification(payload: Payload, data: {
     recipient?: number | string;
 }, collectionSlug?: string): Promise<void>;
 
-type WebhookEvent = 'ticket_created' | 'ticket_resolved' | 'ticket_replied' | 'sla_breached';
+/**
+ * Outbound webhook events. Must stay in sync with the `events` options of the
+ * webhook-endpoints collection.
+ */
+type WebhookEvent = 'ticket_created' | 'ticket_resolved' | 'ticket_replied' | 'ticket_assigned' | 'sla_breached';
 /**
  * Dispatch outbound webhooks for a given event.
  * Fetches all active webhook endpoints matching the event,
@@ -467,7 +564,7 @@ type WebhookEvent = 'ticket_created' | 'ticket_resolved' | 'ticket_replied' | 's
  * @param payload - Payload instance
  * @param slugs - Collection slugs for dynamic collection references
  */
-declare function dispatchWebhook(data: Record<string, unknown>, event: WebhookEvent, payload: BasePayload, slugs: CollectionSlugs): void;
+declare function dispatchWebhook(data: Record<string, unknown>, event: WebhookEvent, payload: BasePayload, slugs: CollectionSlugs): Promise<void>;
 
 interface TicketSynthesisResult {
     summary: string;
@@ -578,4 +675,4 @@ declare function createTicketStatusesCollection(slugs: CollectionSlugs): Collect
  */
 declare function createTicketCollaboratorsCollection(slugs: CollectionSlugs): CollectionConfig;
 
-export { type AIProviderConfig, type ActivityEntryData, type CannedResponseData, type ClientData, type CollectionSlugs, DEFAULT_FEATURES, DEFAULT_INBOUND_EMAIL_LIMITS, DEFAULT_SETTINGS, DEFAULT_SLUGS, DEFAULT_USER_PREFS, type EmailConfig, type InboundEmailInput, type InboundEmailLimits, type InboundEmailValidationError, MemoryRateLimitStore, type MessageData, PayloadRateLimitStore, type RateLimitEntry, type RateLimitStore, RateLimiter, type SatisfactionSurveyData, type SupportFeatures, type SupportPluginConfig, type SupportSettings, type TicketData, type TicketSynthesisResult, type TimeEntryData, type UserPrefs, calculateBusinessHoursDeadline, createAdminNotification, createAssignSlaDeadlines, createAuthLogsCollection, createCannedResponsesCollection, createChatMessagesCollection, createCheckSlaOnReply, createCheckSlaOnResolve, createEmailLogsCollection, createKnowledgeBaseCollection, createLoginEndpoint, createMacrosCollection, createOAuthGoogleEndpoint, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createTrackOpenEndpoint, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, readSupportSettings, readUserPrefs, resolveSlugs, supportPlugin, validateInboundEmailPayload, verifySecret };
+export { type AIProviderConfig, type ActivityEntryData, type CannedResponseData, type ClientData, type CollectionSlugs, DEFAULT_FEATURES, DEFAULT_INBOUND_EMAIL_LIMITS, DEFAULT_SETTINGS, DEFAULT_SLUGS, DEFAULT_TICKETING_FEATURES, DEFAULT_USER_PREFS, type EmailConfig, type InboundEmailInput, type InboundEmailLimits, type InboundEmailValidationError, MemoryRateLimitStore, type MessageData, PayloadRateLimitStore, type RateLimitEntry, type RateLimitStore, RateLimiter, type SatisfactionSurveyData, type SupportFeatures, type SupportPluginConfig, type SupportSettings, type SupportSettingsState, type TicketData, type TicketSynthesisResult, type TicketingFeatures, type TimeEntryData, type UserPrefs, calculateBusinessHoursDeadline, createAdminNotification, createAssignSlaDeadlines, createAuthLogsCollection, createCannedResponsesCollection, createChatMessagesCollection, createCheckSlaOnReply, createCheckSlaOnResolve, createEmailLogsCollection, createKnowledgeBaseCollection, createLoginEndpoint, createMacrosCollection, createOAuthGoogleEndpoint, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createTrackOpenEndpoint, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, normalizeFeatures, projectAutoClose, readSupportSettings, readSupportSettingsState, readUserPrefs, resolveSlugs, stripProjectedFeatures, supportPlugin, validateInboundEmailPayload, verifySecret };