@businessflow/reviews 1.0.0

package/README.md

@@ -0,0 +1,97 @@
+# @businessflow/reviews
+
+Generic review and testimonial management utilities for React and NextJS applications.
+
+## Features
+
+- ⭐ **Star Ratings**: Customizable star rating components
+- 📝 **Review Forms**: Pre-built review submission forms
+- 🎨 **Display Components**: Beautiful testimonial display layouts
+- 🔒 **Secure**: Server-side API handling with reCAPTCHA
+- 📱 **Responsive**: Mobile-friendly components
+- 🎨 **Customizable**: Flexible styling and configuration
+- 📝 **TypeScript**: Full type safety and IntelliSense support
+
+## Installation
+
+```bash
+npm install @businessflow/reviews
+```
+
+## Quick Start
+
+### 1. Create API Routes (NextJS App Router)
+
+```typescript
+// app/api/reviews/featured/route.ts
+import { createReviewHandler } from '@businessflow/reviews/server';
+
+export const GET = createReviewHandler({
+  onFetch: async (params) => {
+    // Fetch from your database/API
+    const reviews = await fetchReviewsFromDB({
+      limit: params?.limit || 10,
+      featured: true
+    });
+    return reviews;
+  }
+});
+
+// app/api/reviews/submit/route.ts
+export const POST = createReviewHandler({
+  onSubmit: async (data) => {
+    // Save to your database/API
+    const result = await saveReviewToDB(data);
+    return {
+      success: !!result.id,
+      reviewId: result.id,
+      message: 'Review submitted successfully'
+    };
+  },
+  recaptcha: {
+    secretKey: process.env.RECAPTCHA_SECRET_KEY!
+  }
+});
+```
+
+### 2. Display Testimonials
+
+```typescript
+import { TestimonialsSection } from '@businessflow/reviews/react';
+
+export default function HomePage() {
+  return (
+    <TestimonialsSection
+      limit={6}
+      layout="grid"
+      showRating={true}
+      autoRefresh={true}
+    />
+  );
+}
+```
+
+### 3. Review Submission Form
+
+```typescript
+import { ReviewForm } from '@businessflow/reviews/react';
+
+export default function ReviewPage() {
+  return (
+    <ReviewForm
+      recaptcha={{ siteKey: process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY! }}
+      onSuccess={(response) => console.log('Review submitted!', response)}
+    />
+  );
+}
+```
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Examples](./examples/)
+- [Component Gallery](./docs/components.md)
+
+## License
+
+MIT

package/dist/client/index.d.mts

@@ -0,0 +1,245 @@
+interface Review {
+    id: string | number;
+    reviewerName: string;
+    reviewerEmail?: string;
+    reviewerTitle?: string;
+    reviewerCompany?: string;
+    reviewerAvatar?: string;
+    rating: number;
+    content?: string;
+    createdAt: string | Date;
+    updatedAt?: string | Date;
+    featured?: boolean;
+    approved?: boolean;
+    metadata?: Record<string, any>;
+}
+interface ReviewFormData {
+    reviewerName: string;
+    reviewerEmail: string;
+    reviewerTitle?: string;
+    reviewerCompany?: string;
+    rating: number;
+    content?: string;
+    [key: string]: any;
+}
+interface ReviewApiResponse {
+    success: boolean;
+    message?: string;
+    reviewId?: string | number;
+    status?: 'pending' | 'approved' | 'rejected';
+    data?: any;
+}
+interface ReviewSubmissionConfig {
+    endpoint: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    maxRetries?: number;
+    timeout?: number;
+    transformRequest?: (data: ReviewFormData) => any;
+    transformResponse?: (response: any) => ReviewApiResponse;
+    onSuccess?: (response: ReviewApiResponse) => void;
+    onError?: (error: Error) => void;
+}
+interface ReviewFetchConfig {
+    endpoint: string;
+    method?: 'GET';
+    headers?: Record<string, string>;
+    maxRetries?: number;
+    timeout?: number;
+    params?: {
+        limit?: number;
+        offset?: number;
+        featured?: boolean;
+        minRating?: number;
+        sortBy?: 'date' | 'rating' | 'name';
+        sortOrder?: 'asc' | 'desc';
+    };
+    transformResponse?: (response: any) => Review[];
+    onError?: (error: Error) => void;
+}
+interface ReviewFieldConfig {
+    show?: boolean;
+    required?: boolean;
+    label?: string;
+    type?: string;
+    placeholder?: string;
+    validation?: ValidationRule[];
+}
+interface ReviewFormConfig {
+    fields?: {
+        reviewerName?: ReviewFieldConfig;
+        reviewerEmail?: ReviewFieldConfig;
+        reviewerTitle?: ReviewFieldConfig;
+        reviewerCompany?: ReviewFieldConfig;
+        rating?: ReviewFieldConfig;
+        content?: ReviewFieldConfig;
+        [key: string]: ReviewFieldConfig | undefined;
+    };
+    recaptcha?: {
+        siteKey: string;
+        action?: string;
+    };
+    styling?: {
+        className?: string;
+        fieldClassName?: string;
+        buttonClassName?: string;
+        errorClassName?: string;
+        starClassName?: string;
+    };
+}
+interface TestimonialDisplayConfig {
+    limit?: number;
+    showRating?: boolean;
+    showDate?: boolean;
+    showAvatar?: boolean;
+    showCompany?: boolean;
+    showTitle?: boolean;
+    layout?: 'grid' | 'list' | 'slider';
+    columns?: number;
+    autoRefresh?: boolean;
+    refreshInterval?: number;
+    styling?: {
+        containerClassName?: string;
+        cardClassName?: string;
+        headerClassName?: string;
+        contentClassName?: string;
+        ratingClassName?: string;
+    };
+}
+interface ValidationRule {
+    type: 'required' | 'email' | 'minLength' | 'maxLength' | 'pattern' | 'custom' | 'rating';
+    value?: string | number;
+    message?: string;
+    validator?: (value: any) => boolean | string;
+}
+interface ValidationErrors {
+    [field: string]: string;
+}
+interface ReviewHandlerConfig {
+    onFetch?: (params?: any) => Promise<Review[]>;
+    onSubmit?: (data: ReviewFormData) => Promise<ReviewApiResponse>;
+    recaptcha?: {
+        secretKey: string;
+        minimumScore?: number;
+    };
+    validation?: {
+        [field: string]: ValidationRule[];
+    };
+    onSuccess?: (data: ReviewFormData, response: ReviewApiResponse) => Promise<void>;
+    onError?: (data: ReviewFormData, error: Error) => Promise<void>;
+    rateLimiter?: (request: Request) => Promise<boolean>;
+}
+interface StarRatingProps {
+    rating: number;
+    maxRating?: number;
+    editable?: boolean;
+    onChange?: (rating: number) => void;
+    size?: 'small' | 'medium' | 'large';
+    className?: string;
+}
+
+/**
+ * Generic review client for fetching and submitting reviews
+ */
+declare class ReviewClient {
+    private fetchConfig?;
+    private submitConfig?;
+    private maxRetries;
+    private timeout;
+    constructor(config: {
+        fetchConfig?: ReviewFetchConfig;
+        submitConfig?: ReviewSubmissionConfig;
+        maxRetries?: number;
+        timeout?: number;
+    });
+    /**
+     * Fetch reviews with retry logic
+     */
+    fetchReviews(params?: {
+        limit?: number;
+        offset?: number;
+        featured?: boolean;
+        minRating?: number;
+    }, retryCount?: number): Promise<Review[]>;
+    /**
+     * Submit a review with retry logic
+     */
+    submitReview(reviewData: ReviewFormData, retryCount?: number): Promise<ReviewApiResponse>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: {
+        fetchConfig?: Partial<ReviewFetchConfig>;
+        submitConfig?: Partial<ReviewSubmissionConfig>;
+    }): void;
+}
+
+/**
+ * Default validation rules for review forms
+ */
+declare const DEFAULT_REVIEW_VALIDATION_RULES: {
+    reviewerName: ({
+        type: "required";
+        message: string;
+        value?: undefined;
+    } | {
+        type: "minLength";
+        value: number;
+        message: string;
+    } | {
+        type: "maxLength";
+        value: number;
+        message: string;
+    })[];
+    reviewerEmail: ({
+        type: "required";
+        message: string;
+    } | {
+        type: "email";
+        message: string;
+    })[];
+    rating: ({
+        type: "required";
+        message: string;
+    } | {
+        type: "rating";
+        message: string;
+    })[];
+    content: {
+        type: "maxLength";
+        value: number;
+        message: string;
+    }[];
+    reviewerTitle: {
+        type: "maxLength";
+        value: number;
+        message: string;
+    }[];
+    reviewerCompany: {
+        type: "maxLength";
+        value: number;
+        message: string;
+    }[];
+};
+/**
+ * Validate review form data
+ */
+declare function validateReviewData(data: ReviewFormData, customRules?: {
+    [field: string]: ValidationRule[];
+}): ValidationErrors | null;
+/**
+ * Validate a single field - useful for real-time validation
+ */
+declare function validateSingleReviewField(field: string, value: any, customRules?: {
+    [field: string]: ValidationRule[];
+}): string | null;
+/**
+ * Check if rating is valid (1-5 stars)
+ */
+declare function isValidRating(rating: number): boolean;
+/**
+ * Sanitize review form data - trim strings and remove empty optional fields
+ */
+declare function sanitizeReviewData(data: ReviewFormData): ReviewFormData;
+
+export { DEFAULT_REVIEW_VALIDATION_RULES, type Review, type ReviewApiResponse, ReviewClient, type ReviewFetchConfig, type ReviewFieldConfig, type ReviewFormConfig, type ReviewFormData, type ReviewHandlerConfig, type ReviewSubmissionConfig, type StarRatingProps, type TestimonialDisplayConfig, type ValidationErrors, type ValidationRule, isValidRating, sanitizeReviewData, validateReviewData, validateSingleReviewField };

package/dist/client/index.d.ts

@@ -0,0 +1,245 @@
+interface Review {
+    id: string | number;
+    reviewerName: string;
+    reviewerEmail?: string;
+    reviewerTitle?: string;
+    reviewerCompany?: string;
+    reviewerAvatar?: string;
+    rating: number;
+    content?: string;
+    createdAt: string | Date;
+    updatedAt?: string | Date;
+    featured?: boolean;
+    approved?: boolean;
+    metadata?: Record<string, any>;
+}
+interface ReviewFormData {
+    reviewerName: string;
+    reviewerEmail: string;
+    reviewerTitle?: string;
+    reviewerCompany?: string;
+    rating: number;
+    content?: string;
+    [key: string]: any;
+}
+interface ReviewApiResponse {
+    success: boolean;
+    message?: string;
+    reviewId?: string | number;
+    status?: 'pending' | 'approved' | 'rejected';
+    data?: any;
+}
+interface ReviewSubmissionConfig {
+    endpoint: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    maxRetries?: number;
+    timeout?: number;
+    transformRequest?: (data: ReviewFormData) => any;
+    transformResponse?: (response: any) => ReviewApiResponse;
+    onSuccess?: (response: ReviewApiResponse) => void;
+    onError?: (error: Error) => void;
+}
+interface ReviewFetchConfig {
+    endpoint: string;
+    method?: 'GET';
+    headers?: Record<string, string>;
+    maxRetries?: number;
+    timeout?: number;
+    params?: {
+        limit?: number;
+        offset?: number;
+        featured?: boolean;
+        minRating?: number;
+        sortBy?: 'date' | 'rating' | 'name';
+        sortOrder?: 'asc' | 'desc';
+    };
+    transformResponse?: (response: any) => Review[];
+    onError?: (error: Error) => void;
+}
+interface ReviewFieldConfig {
+    show?: boolean;
+    required?: boolean;
+    label?: string;
+    type?: string;
+    placeholder?: string;
+    validation?: ValidationRule[];
+}
+interface ReviewFormConfig {
+    fields?: {
+        reviewerName?: ReviewFieldConfig;
+        reviewerEmail?: ReviewFieldConfig;
+        reviewerTitle?: ReviewFieldConfig;
+        reviewerCompany?: ReviewFieldConfig;
+        rating?: ReviewFieldConfig;
+        content?: ReviewFieldConfig;
+        [key: string]: ReviewFieldConfig | undefined;
+    };
+    recaptcha?: {
+        siteKey: string;
+        action?: string;
+    };
+    styling?: {
+        className?: string;
+        fieldClassName?: string;
+        buttonClassName?: string;
+        errorClassName?: string;
+        starClassName?: string;
+    };
+}
+interface TestimonialDisplayConfig {
+    limit?: number;
+    showRating?: boolean;
+    showDate?: boolean;
+    showAvatar?: boolean;
+    showCompany?: boolean;
+    showTitle?: boolean;
+    layout?: 'grid' | 'list' | 'slider';
+    columns?: number;
+    autoRefresh?: boolean;
+    refreshInterval?: number;
+    styling?: {
+        containerClassName?: string;
+        cardClassName?: string;
+        headerClassName?: string;
+        contentClassName?: string;
+        ratingClassName?: string;
+    };
+}
+interface ValidationRule {
+    type: 'required' | 'email' | 'minLength' | 'maxLength' | 'pattern' | 'custom' | 'rating';
+    value?: string | number;
+    message?: string;
+    validator?: (value: any) => boolean | string;
+}
+interface ValidationErrors {
+    [field: string]: string;
+}
+interface ReviewHandlerConfig {
+    onFetch?: (params?: any) => Promise<Review[]>;
+    onSubmit?: (data: ReviewFormData) => Promise<ReviewApiResponse>;
+    recaptcha?: {
+        secretKey: string;
+        minimumScore?: number;
+    };
+    validation?: {
+        [field: string]: ValidationRule[];
+    };
+    onSuccess?: (data: ReviewFormData, response: ReviewApiResponse) => Promise<void>;
+    onError?: (data: ReviewFormData, error: Error) => Promise<void>;
+    rateLimiter?: (request: Request) => Promise<boolean>;
+}
+interface StarRatingProps {
+    rating: number;
+    maxRating?: number;
+    editable?: boolean;
+    onChange?: (rating: number) => void;
+    size?: 'small' | 'medium' | 'large';
+    className?: string;
+}
+
+/**
+ * Generic review client for fetching and submitting reviews
+ */
+declare class ReviewClient {
+    private fetchConfig?;
+    private submitConfig?;
+    private maxRetries;
+    private timeout;
+    constructor(config: {
+        fetchConfig?: ReviewFetchConfig;
+        submitConfig?: ReviewSubmissionConfig;
+        maxRetries?: number;
+        timeout?: number;
+    });
+    /**
+     * Fetch reviews with retry logic
+     */
+    fetchReviews(params?: {
+        limit?: number;
+        offset?: number;
+        featured?: boolean;
+        minRating?: number;
+    }, retryCount?: number): Promise<Review[]>;
+    /**
+     * Submit a review with retry logic
+     */
+    submitReview(reviewData: ReviewFormData, retryCount?: number): Promise<ReviewApiResponse>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: {
+        fetchConfig?: Partial<ReviewFetchConfig>;
+        submitConfig?: Partial<ReviewSubmissionConfig>;
+    }): void;
+}
+
+/**
+ * Default validation rules for review forms
+ */
+declare const DEFAULT_REVIEW_VALIDATION_RULES: {
+    reviewerName: ({
+        type: "required";
+        message: string;
+        value?: undefined;
+    } | {
+        type: "minLength";
+        value: number;
+        message: string;
+    } | {
+        type: "maxLength";
+        value: number;
+        message: string;
+    })[];
+    reviewerEmail: ({
+        type: "required";
+        message: string;
+    } | {
+        type: "email";
+        message: string;
+    })[];
+    rating: ({
+        type: "required";
+        message: string;
+    } | {
+        type: "rating";
+        message: string;
+    })[];
+    content: {
+        type: "maxLength";
+        value: number;
+        message: string;
+    }[];
+    reviewerTitle: {
+        type: "maxLength";
+        value: number;
+        message: string;
+    }[];
+    reviewerCompany: {
+        type: "maxLength";
+        value: number;
+        message: string;
+    }[];
+};
+/**
+ * Validate review form data
+ */
+declare function validateReviewData(data: ReviewFormData, customRules?: {
+    [field: string]: ValidationRule[];
+}): ValidationErrors | null;
+/**
+ * Validate a single field - useful for real-time validation
+ */
+declare function validateSingleReviewField(field: string, value: any, customRules?: {
+    [field: string]: ValidationRule[];
+}): string | null;
+/**
+ * Check if rating is valid (1-5 stars)
+ */
+declare function isValidRating(rating: number): boolean;
+/**
+ * Sanitize review form data - trim strings and remove empty optional fields
+ */
+declare function sanitizeReviewData(data: ReviewFormData): ReviewFormData;
+
+export { DEFAULT_REVIEW_VALIDATION_RULES, type Review, type ReviewApiResponse, ReviewClient, type ReviewFetchConfig, type ReviewFieldConfig, type ReviewFormConfig, type ReviewFormData, type ReviewHandlerConfig, type ReviewSubmissionConfig, type StarRatingProps, type TestimonialDisplayConfig, type ValidationErrors, type ValidationRule, isValidRating, sanitizeReviewData, validateReviewData, validateSingleReviewField };