@consilioweb/payload-support 1.1.0 → 2.0.0

package/dist/index.d.cts

@@ -1,4 +1,69 @@
-import { Plugin, Payload, BasePayload, CollectionAfterChangeHook, CollectionConfig } from 'payload';
+import { Payload, PayloadRequest, Plugin, Endpoint, BasePayload, CollectionAfterChangeHook, CollectionConfig } from 'payload';
+
+interface RateLimitEntry {
+    count: number;
+    resetAt: number;
+}
+interface RateLimitStore {
+    increment(key: string, windowMs: number, context?: unknown): Promise<RateLimitEntry>;
+    reset(key: string, context?: unknown): Promise<void>;
+}
+/**
+ * Process-local fallback store. Applications running more than one process
+ * should provide a persistent RateLimitStore through the plugin options.
+ */
+declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly entries;
+    increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+    reset(key: string): Promise<void>;
+}
+declare class PayloadRateLimitStore implements RateLimitStore {
+    private readonly collectionSlug;
+    constructor(collectionSlug?: string);
+    increment(key: string, windowMs: number, context?: unknown): Promise<RateLimitEntry>;
+    reset(key: string, context?: unknown): Promise<void>;
+    private resolveContext;
+}
+declare class RateLimiter {
+    private readonly windowMs;
+    private readonly maxRequests;
+    private readonly store;
+    constructor(windowMs: number, maxRequests: number, store?: RateLimitStore);
+    check(key: string, context?: unknown): Promise<boolean>;
+    reset(key: string, context?: unknown): Promise<void>;
+}
+
+interface InboundEmailLimits {
+    maxRequestBytes: number;
+    maxAttachmentBytes: number;
+    maxAttachments: number;
+    maxSubjectLength: number;
+    maxNameLength: number;
+    maxEmailLength: number;
+    maxBodyLength: number;
+}
+declare const DEFAULT_INBOUND_EMAIL_LIMITS: InboundEmailLimits;
+interface InboundAttachment {
+    filename?: string;
+    size?: number;
+    content?: string;
+}
+interface InboundEmailInput {
+    senderEmail?: string;
+    senderName?: string;
+    recipientEmail?: string;
+    cc?: string;
+    subject?: string;
+    body?: string;
+    htmlBody?: string;
+    attachments?: InboundAttachment[];
+}
+interface InboundEmailValidationError {
+    code: 'request_too_large' | 'too_many_attachments' | 'attachment_too_large' | 'text_field_too_large';
+    status: 413;
+}
+declare function verifySecret(provided: string | null | undefined, expected: string | null | undefined): boolean;
+declare function validateInboundEmailPayload(input: InboundEmailInput, contentLength?: number, limits?: InboundEmailLimits): InboundEmailValidationError | null;
 
 interface SupportFeatures {
     /** Time tracking: timer, manual entries, billing */
@@ -69,6 +134,59 @@ interface EmailConfig {
     fromName?: string;
     replyTo?: string;
 }
+interface SmsSendResult {
+    sent: boolean;
+    skipped?: boolean;
+    error?: string;
+}
+interface SmsAdapter {
+    isConfigured?: () => boolean;
+    send: (input: {
+        message: string;
+        to: string;
+        payload: Payload;
+        ticket: Record<string, unknown>;
+        client: Record<string, unknown>;
+    }) => Promise<SmsSendResult>;
+}
+interface SupportCapabilities {
+    /** Optional SMS transport. The module never depends on a concrete provider. */
+    sms?: {
+        adapter: SmsAdapter;
+        buildMessage?: (input: {
+            client: Record<string, unknown>;
+            ticket: Record<string, unknown>;
+        }) => string | Promise<string>;
+    };
+    /** Native daily/weekly notification queue. */
+    digests?: boolean;
+    /** Incoming email business adapter, protected and validated by the module. */
+    inboundEmail?: {
+        handle: (req: PayloadRequest, input: InboundEmailInput) => Promise<Response>;
+        secret?: string;
+        secretHeader?: string;
+    };
+    /** Generate a short, editable display title after ticket creation. */
+    aiTitles?: {
+        generate: (payload: Payload, ticketId: number | string) => Promise<unknown>;
+    };
+    /** Override the module's default resolved-ticket synthesis generator. */
+    aiSummaries?: {
+        generate: (payload: Payload, ticketId: number | string) => Promise<unknown>;
+    };
+    /** Persist billing lines and their invoicing state. */
+    detailedBilling?: boolean;
+    /** Persist pro-bono work and its estimated value. */
+    volunteering?: boolean;
+    /** Best-effort cleanup of noisy messages after an inbound client reply. */
+    threadCleanup?: {
+        clean: (payload: Payload, ticketId: number | string, messageId: number | string) => Promise<unknown>;
+    };
+    /** Deployment-specific project suggestion adapter. */
+    projectSuggestions?: {
+        suggest: (req: PayloadRequest) => Promise<Response>;
+    };
+}
 interface SupportPluginConfig {
     /** Enable/disable individual features (all enabled by default) */
     features?: SupportFeatures;
@@ -76,6 +194,15 @@ interface SupportPluginConfig {
     ai?: AIProviderConfig;
     /** Email configuration for ticket notifications */
     email?: EmailConfig;
+    /** Shared rate-limit storage. Defaults to process-local memory. */
+    rateLimitStore?: RateLimitStore | 'payload';
+    /** Sequential ticket number formatting. */
+    ticketNumber?: {
+        prefix?: string;
+        padding?: number;
+    };
+    /** Optional generic capabilities backed by deployment-specific adapters. */
+    capabilities?: SupportCapabilities;
     /** Locale: 'fr' or 'en' (default: 'fr') */
     locale?: 'fr' | 'en';
     /** Nav group label in Payload admin sidebar */
@@ -116,6 +243,8 @@ interface SupportPluginConfig {
         macros?: string;
         ticketStatuses?: string;
         ticketFeedback?: string;
+        rateLimits?: string;
+        counters?: string;
     };
     /** Admin notification collection slug (default: 'admin-notifications') */
     notificationSlug?: string;
@@ -241,6 +370,8 @@ interface CollectionSlugs {
     automationRules: string;
     supportTeams: string;
     pushSubscriptions: string;
+    rateLimits: string;
+    counters: string;
     users: string;
     media: string;
 }
@@ -285,6 +416,29 @@ declare const DEFAULT_USER_PREFS: UserPrefs;
 declare function readSupportSettings(payload: Payload): Promise<SupportSettings>;
 declare function readUserPrefs(payload: Payload, userId: string | number): 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 }
+ */
+interface OAuthGoogleOptions {
+    allowedEmailDomains?: string[];
+}
+declare function createOAuthGoogleEndpoint(slugs: CollectionSlugs, options?: OAuthGoogleOptions): Endpoint;
+
+/**
+ * GET /api/support/track-open?t=<ticketId>&m=<messageId>&sig=<hmac>
+ * Tracking pixel for email open detection. No auth required.
+ * Validates HMAC signature to prevent enumeration attacks.
+ */
+declare function createTrackOpenEndpoint(slugs: CollectionSlugs): Endpoint;
+
+/**
+ * POST /api/support/login
+ * Client login endpoint.
+ */
+declare function createLoginEndpoint(slugs: CollectionSlugs, store?: RateLimitStore): Endpoint;
+
 /**
  * Helper to create an admin notification.
  * Can be called from any hook or endpoint.
@@ -370,13 +524,21 @@ declare function createTicketsCollection(slugs: CollectionSlugs, options?: {
     projectCollectionSlug?: string;
     documentsCollectionSlug?: string;
     notificationSlug?: string;
+    ticketNumber?: {
+        prefix?: string;
+        padding?: number;
+    };
+    capabilities?: SupportCapabilities;
 }): CollectionConfig;
 
 declare function createTicketMessagesCollection(slugs: CollectionSlugs, options?: {
     notificationSlug?: string;
+    capabilities?: SupportCapabilities;
 }): CollectionConfig;
 
-declare function createSupportClientsCollection(slugs: CollectionSlugs): CollectionConfig;
+declare function createSupportClientsCollection(slugs: CollectionSlugs, options?: {
+    capabilities?: SupportCapabilities;
+}): CollectionConfig;
 
 declare function createTimeEntriesCollection(slugs: CollectionSlugs): CollectionConfig;
 
@@ -416,4 +578,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_SETTINGS, DEFAULT_SLUGS, DEFAULT_USER_PREFS, type EmailConfig, type MessageData, 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, createMacrosCollection, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, readSupportSettings, readUserPrefs, resolveSlugs, supportPlugin };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,69 @@
-import { Plugin, Payload, BasePayload, CollectionAfterChangeHook, CollectionConfig } from 'payload';
+import { Payload, PayloadRequest, Plugin, Endpoint, BasePayload, CollectionAfterChangeHook, CollectionConfig } from 'payload';
+
+interface RateLimitEntry {
+    count: number;
+    resetAt: number;
+}
+interface RateLimitStore {
+    increment(key: string, windowMs: number, context?: unknown): Promise<RateLimitEntry>;
+    reset(key: string, context?: unknown): Promise<void>;
+}
+/**
+ * Process-local fallback store. Applications running more than one process
+ * should provide a persistent RateLimitStore through the plugin options.
+ */
+declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly entries;
+    increment(key: string, windowMs: number): Promise<RateLimitEntry>;
+    reset(key: string): Promise<void>;
+}
+declare class PayloadRateLimitStore implements RateLimitStore {
+    private readonly collectionSlug;
+    constructor(collectionSlug?: string);
+    increment(key: string, windowMs: number, context?: unknown): Promise<RateLimitEntry>;
+    reset(key: string, context?: unknown): Promise<void>;
+    private resolveContext;
+}
+declare class RateLimiter {
+    private readonly windowMs;
+    private readonly maxRequests;
+    private readonly store;
+    constructor(windowMs: number, maxRequests: number, store?: RateLimitStore);
+    check(key: string, context?: unknown): Promise<boolean>;
+    reset(key: string, context?: unknown): Promise<void>;
+}
+
+interface InboundEmailLimits {
+    maxRequestBytes: number;
+    maxAttachmentBytes: number;
+    maxAttachments: number;
+    maxSubjectLength: number;
+    maxNameLength: number;
+    maxEmailLength: number;
+    maxBodyLength: number;
+}
+declare const DEFAULT_INBOUND_EMAIL_LIMITS: InboundEmailLimits;
+interface InboundAttachment {
+    filename?: string;
+    size?: number;
+    content?: string;
+}
+interface InboundEmailInput {
+    senderEmail?: string;
+    senderName?: string;
+    recipientEmail?: string;
+    cc?: string;
+    subject?: string;
+    body?: string;
+    htmlBody?: string;
+    attachments?: InboundAttachment[];
+}
+interface InboundEmailValidationError {
+    code: 'request_too_large' | 'too_many_attachments' | 'attachment_too_large' | 'text_field_too_large';
+    status: 413;
+}
+declare function verifySecret(provided: string | null | undefined, expected: string | null | undefined): boolean;
+declare function validateInboundEmailPayload(input: InboundEmailInput, contentLength?: number, limits?: InboundEmailLimits): InboundEmailValidationError | null;
 
 interface SupportFeatures {
     /** Time tracking: timer, manual entries, billing */
@@ -69,6 +134,59 @@ interface EmailConfig {
     fromName?: string;
     replyTo?: string;
 }
+interface SmsSendResult {
+    sent: boolean;
+    skipped?: boolean;
+    error?: string;
+}
+interface SmsAdapter {
+    isConfigured?: () => boolean;
+    send: (input: {
+        message: string;
+        to: string;
+        payload: Payload;
+        ticket: Record<string, unknown>;
+        client: Record<string, unknown>;
+    }) => Promise<SmsSendResult>;
+}
+interface SupportCapabilities {
+    /** Optional SMS transport. The module never depends on a concrete provider. */
+    sms?: {
+        adapter: SmsAdapter;
+        buildMessage?: (input: {
+            client: Record<string, unknown>;
+            ticket: Record<string, unknown>;
+        }) => string | Promise<string>;
+    };
+    /** Native daily/weekly notification queue. */
+    digests?: boolean;
+    /** Incoming email business adapter, protected and validated by the module. */
+    inboundEmail?: {
+        handle: (req: PayloadRequest, input: InboundEmailInput) => Promise<Response>;
+        secret?: string;
+        secretHeader?: string;
+    };
+    /** Generate a short, editable display title after ticket creation. */
+    aiTitles?: {
+        generate: (payload: Payload, ticketId: number | string) => Promise<unknown>;
+    };
+    /** Override the module's default resolved-ticket synthesis generator. */
+    aiSummaries?: {
+        generate: (payload: Payload, ticketId: number | string) => Promise<unknown>;
+    };
+    /** Persist billing lines and their invoicing state. */
+    detailedBilling?: boolean;
+    /** Persist pro-bono work and its estimated value. */
+    volunteering?: boolean;
+    /** Best-effort cleanup of noisy messages after an inbound client reply. */
+    threadCleanup?: {
+        clean: (payload: Payload, ticketId: number | string, messageId: number | string) => Promise<unknown>;
+    };
+    /** Deployment-specific project suggestion adapter. */
+    projectSuggestions?: {
+        suggest: (req: PayloadRequest) => Promise<Response>;
+    };
+}
 interface SupportPluginConfig {
     /** Enable/disable individual features (all enabled by default) */
     features?: SupportFeatures;
@@ -76,6 +194,15 @@ interface SupportPluginConfig {
     ai?: AIProviderConfig;
     /** Email configuration for ticket notifications */
     email?: EmailConfig;
+    /** Shared rate-limit storage. Defaults to process-local memory. */
+    rateLimitStore?: RateLimitStore | 'payload';
+    /** Sequential ticket number formatting. */
+    ticketNumber?: {
+        prefix?: string;
+        padding?: number;
+    };
+    /** Optional generic capabilities backed by deployment-specific adapters. */
+    capabilities?: SupportCapabilities;
     /** Locale: 'fr' or 'en' (default: 'fr') */
     locale?: 'fr' | 'en';
     /** Nav group label in Payload admin sidebar */
@@ -116,6 +243,8 @@ interface SupportPluginConfig {
         macros?: string;
         ticketStatuses?: string;
         ticketFeedback?: string;
+        rateLimits?: string;
+        counters?: string;
     };
     /** Admin notification collection slug (default: 'admin-notifications') */
     notificationSlug?: string;
@@ -241,6 +370,8 @@ interface CollectionSlugs {
     automationRules: string;
     supportTeams: string;
     pushSubscriptions: string;
+    rateLimits: string;
+    counters: string;
     users: string;
     media: string;
 }
@@ -285,6 +416,29 @@ declare const DEFAULT_USER_PREFS: UserPrefs;
 declare function readSupportSettings(payload: Payload): Promise<SupportSettings>;
 declare function readUserPrefs(payload: Payload, userId: string | number): 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 }
+ */
+interface OAuthGoogleOptions {
+    allowedEmailDomains?: string[];
+}
+declare function createOAuthGoogleEndpoint(slugs: CollectionSlugs, options?: OAuthGoogleOptions): Endpoint;
+
+/**
+ * GET /api/support/track-open?t=<ticketId>&m=<messageId>&sig=<hmac>
+ * Tracking pixel for email open detection. No auth required.
+ * Validates HMAC signature to prevent enumeration attacks.
+ */
+declare function createTrackOpenEndpoint(slugs: CollectionSlugs): Endpoint;
+
+/**
+ * POST /api/support/login
+ * Client login endpoint.
+ */
+declare function createLoginEndpoint(slugs: CollectionSlugs, store?: RateLimitStore): Endpoint;
+
 /**
  * Helper to create an admin notification.
  * Can be called from any hook or endpoint.
@@ -370,13 +524,21 @@ declare function createTicketsCollection(slugs: CollectionSlugs, options?: {
     projectCollectionSlug?: string;
     documentsCollectionSlug?: string;
     notificationSlug?: string;
+    ticketNumber?: {
+        prefix?: string;
+        padding?: number;
+    };
+    capabilities?: SupportCapabilities;
 }): CollectionConfig;
 
 declare function createTicketMessagesCollection(slugs: CollectionSlugs, options?: {
     notificationSlug?: string;
+    capabilities?: SupportCapabilities;
 }): CollectionConfig;
 
-declare function createSupportClientsCollection(slugs: CollectionSlugs): CollectionConfig;
+declare function createSupportClientsCollection(slugs: CollectionSlugs, options?: {
+    capabilities?: SupportCapabilities;
+}): CollectionConfig;
 
 declare function createTimeEntriesCollection(slugs: CollectionSlugs): CollectionConfig;
 
@@ -416,4 +578,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_SETTINGS, DEFAULT_SLUGS, DEFAULT_USER_PREFS, type EmailConfig, type MessageData, 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, createMacrosCollection, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, readSupportSettings, readUserPrefs, resolveSlugs, supportPlugin };
+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 };