@consilioweb/payload-support 2.0.1 → 4.0.0

package/dist/index.d.cts

@@ -28,7 +28,19 @@ declare class RateLimiter {
     private readonly windowMs;
     private readonly maxRequests;
     private readonly store;
-    constructor(windowMs: number, maxRequests: number, store?: RateLimitStore);
+    private readonly prefix;
+    /**
+     * @param namespace  Endpoint-scoped prefix for every key this limiter writes.
+     *   The store is SHARED (`rateLimitStore: 'payload'` builds one instance for
+     *   all endpoints), and the raw keys collide across endpoints: `ip` was used
+     *   by both the login and the chatbot limiter — 10 forged chatbot requests
+     *   locked a victim out of the portal for 15 minutes — and `String(user.id)`
+     *   by five different endpoints. Always pass one; it is optional only because
+     *   `RateLimiter` is part of the published API surface.
+     */
+    constructor(windowMs: number, maxRequests: number, store?: RateLimitStore, namespace?: string);
+    /** The key actually written to the store. Exposed for assertions in tests. */
+    scopedKey(key: string): string;
     check(key: string, context?: unknown): Promise<boolean>;
     reset(key: string, context?: unknown): Promise<void>;
 }
@@ -381,6 +393,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 +499,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,13 +508,26 @@ interface UserPrefs {
 }
 declare const DEFAULT_SETTINGS: SupportSettings;
 declare const DEFAULT_USER_PREFS: UserPrefs;
-declare function readSupportSettings(payload: Payload): Promise<SupportSettings>;
-declare function readUserPrefs(payload: Payload, userId: string | number): Promise<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, staffSlug?: string): Promise<SupportSettingsState>;
+declare function readSupportSettings(payload: Payload, staffSlug?: string): Promise<SupportSettings>;
+declare function readUserPrefs(payload: Payload, userId: string | number, staffSlug?: string): Promise<UserPrefs>;
 
 /**
  * POST /api/support/oauth/google
  * Google OAuth — handles both login redirect and callback.
- * Body: { action: 'login' } or { code: string, state: string, cookieState: string }
+ * Body: { action: 'login' } or { code: string, state: string }
+ *
+ * The CSRF state is NOT taken from the body: `action: 'login'` issues it as an
+ * HttpOnly cookie and the callback reads it back from the `Cookie` header.
  */
 interface OAuthGoogleOptions {
     allowedEmailDomains?: string[];
@@ -455,7 +563,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 +579,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 +690,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

@@ -28,7 +28,19 @@ declare class RateLimiter {
     private readonly windowMs;
     private readonly maxRequests;
     private readonly store;
-    constructor(windowMs: number, maxRequests: number, store?: RateLimitStore);
+    private readonly prefix;
+    /**
+     * @param namespace  Endpoint-scoped prefix for every key this limiter writes.
+     *   The store is SHARED (`rateLimitStore: 'payload'` builds one instance for
+     *   all endpoints), and the raw keys collide across endpoints: `ip` was used
+     *   by both the login and the chatbot limiter — 10 forged chatbot requests
+     *   locked a victim out of the portal for 15 minutes — and `String(user.id)`
+     *   by five different endpoints. Always pass one; it is optional only because
+     *   `RateLimiter` is part of the published API surface.
+     */
+    constructor(windowMs: number, maxRequests: number, store?: RateLimitStore, namespace?: string);
+    /** The key actually written to the store. Exposed for assertions in tests. */
+    scopedKey(key: string): string;
     check(key: string, context?: unknown): Promise<boolean>;
     reset(key: string, context?: unknown): Promise<void>;
 }
@@ -381,6 +393,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 +499,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,13 +508,26 @@ interface UserPrefs {
 }
 declare const DEFAULT_SETTINGS: SupportSettings;
 declare const DEFAULT_USER_PREFS: UserPrefs;
-declare function readSupportSettings(payload: Payload): Promise<SupportSettings>;
-declare function readUserPrefs(payload: Payload, userId: string | number): Promise<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, staffSlug?: string): Promise<SupportSettingsState>;
+declare function readSupportSettings(payload: Payload, staffSlug?: string): Promise<SupportSettings>;
+declare function readUserPrefs(payload: Payload, userId: string | number, staffSlug?: string): Promise<UserPrefs>;
 
 /**
  * POST /api/support/oauth/google
  * Google OAuth — handles both login redirect and callback.
- * Body: { action: 'login' } or { code: string, state: string, cookieState: string }
+ * Body: { action: 'login' } or { code: string, state: string }
+ *
+ * The CSRF state is NOT taken from the body: `action: 'login'` issues it as an
+ * HttpOnly cookie and the callback reads it back from the `Cookie` header.
  */
 interface OAuthGoogleOptions {
     allowedEmailDomains?: string[];
@@ -455,7 +563,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 +579,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 +690,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 };