@mohasinac/appkit 2.3.0 → 2.3.1

package/dist/features/faq/hooks/useFaqList.js

@@ -0,0 +1,34 @@
+import { useQuery } from "@tanstack/react-query";
+import { apiClient } from "../../../http";
+import { FAQ_ENDPOINTS } from "../../../constants/api-endpoints";
+export function useFaqList(options = {}) {
+    const params = new URLSearchParams();
+    if (options.category)
+        params.set("category", options.category);
+    if (options.search)
+        params.set("search", options.search);
+    if (options.tags && options.tags.length > 0) {
+        params.set("tags", options.tags.join(","));
+    }
+    if (options.showOnHomepage !== undefined) {
+        params.set("showOnHomepage", String(options.showOnHomepage));
+    }
+    params.set("page", String(options.page ?? 1));
+    params.set("pageSize", String(options.pageSize ?? 20));
+    if (options.sorts)
+        params.set("sorts", options.sorts);
+    const queryString = params.toString();
+    const query = useQuery({
+        queryKey: ["faqs", queryString],
+        queryFn: () => apiClient.get(`${FAQ_ENDPOINTS.LIST}${queryString ? `?${queryString}` : ""}`),
+        enabled: options.enabled,
+        initialData: options.initialData,
+        staleTime: 5 * 60 * 1000,
+    });
+    return {
+        ...query,
+        faqs: query.data?.items ?? [],
+        total: query.data?.total ?? 0,
+        categories: query.data?.categories ?? [],
+    };
+}

package/dist/features/faq/hooks/useFaqVote.d.ts

@@ -0,0 +1,14 @@
+export interface VoteFaqInput {
+    faqId: string;
+    vote: "helpful" | "not_helpful" | "not-helpful";
+}
+export interface VoteFaqResult {
+    helpfulCount: number;
+    notHelpfulCount?: number;
+    userVote?: VoteFaqInput["vote"] | null;
+}
+export interface UseFaqVoteOptions {
+    mutationFn?: (data: VoteFaqInput) => Promise<VoteFaqResult>;
+    endpoint?: string;
+}
+export declare function useFaqVote(options?: UseFaqVoteOptions): import("@tanstack/react-query").UseMutationResult<VoteFaqResult, Error, VoteFaqInput, unknown>;

package/dist/features/faq/hooks/useFaqVote.js

@@ -0,0 +1,9 @@
+import { useMutation } from "@tanstack/react-query";
+import { apiClient } from "../../../http";
+import { FAQ_ENDPOINTS } from "../../../constants/api-endpoints";
+export function useFaqVote(options) {
+    return useMutation({
+        mutationFn: options?.mutationFn ??
+            ((data) => apiClient.post(options?.endpoint ?? FAQ_ENDPOINTS.VOTE, data)),
+    });
+}

package/dist/features/faq/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./hooks/useFAQs";
+export * from "./hooks/useFaqList";
+export * from "./hooks/useFaqVote";
+export * from "./components";
+export * from "./schemas";
+export * from "./columns";
+export { manifest } from "./manifest";

package/dist/features/faq/index.js

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./hooks/useFAQs";
+export * from "./hooks/useFaqList";
+export * from "./hooks/useFaqVote";
+export * from "./components";
+export * from "./schemas";
+export * from "./columns";
+export { manifest } from "./manifest";

package/dist/features/faq/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureManifest } from "../../contracts";
+export declare const manifest: FeatureManifest;

package/dist/features/faq/manifest.js

@@ -0,0 +1,10 @@
+export const manifest = {
+    name: "faq",
+    i18nNamespace: "faq",
+    envKeys: [],
+    routes: [{ segment: "[locale]/faq", exports: { default: "FAQPageView" } }],
+    apiRoutes: [
+        { segment: "api/faqs", methods: ["GET", "POST"] },
+        { segment: "api/faqs/[id]", methods: ["GET", "PATCH", "DELETE"] },
+    ],
+};

package/dist/features/faq/messages/en.json

@@ -0,0 +1,14 @@
+{
+  "title": "Frequently Asked Questions",
+  "all": "All",
+  "noFAQs": "No questions found",
+  "category": {
+    "orders_payment": "Orders & Payment",
+    "shipping_delivery": "Shipping & Delivery",
+    "returns_refunds": "Returns & Refunds",
+    "product_information": "Product Information",
+    "account_security": "Account & Security",
+    "technical_support": "Technical Support",
+    "general": "General"
+  }
+}

package/dist/features/faq/repository/faqs.repository.d.ts

@@ -0,0 +1,42 @@
+import type { IRepository, PagedResult, SieveQuery } from "../../../contracts";
+import { BaseRepository } from "../../../providers/db-firebase";
+import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
+import type { FAQ, FAQCategory } from "../types";
+import { FAQDocument, FAQCreateInput, FAQWithInterpolatedAnswer } from "../schemas";
+export declare class FAQsRepository {
+    private readonly repo;
+    constructor(repo: IRepository<FAQ>);
+    findAll(query?: SieveQuery): Promise<PagedResult<FAQ>>;
+    findByCategory(category: FAQCategory): Promise<FAQ[]>;
+    findForHomepage(): Promise<FAQ[]>;
+    findForFooter(): Promise<FAQ[]>;
+    findById(id: string): Promise<FAQ | null>;
+    create(data: Omit<FAQ, "id">): Promise<FAQ>;
+    update(id: string, data: Partial<FAQ>): Promise<FAQ>;
+    delete(id: string): Promise<void>;
+}
+export declare class FirebaseFAQsRepository extends BaseRepository<FAQDocument> {
+    static readonly SIEVE_FIELDS: FirebaseSieveFields;
+    constructor();
+    private buildSearchTokens;
+    create(data: Partial<FAQDocument>): Promise<FAQDocument>;
+    update(id: string, data: Partial<FAQDocument>): Promise<FAQDocument>;
+    list(model: SieveModel, opts?: {
+        tags?: string[];
+        search?: string;
+    }): Promise<FirebaseSieveResult<FAQDocument>>;
+    getFAQBySlug(slug: string): Promise<FAQDocument | null>;
+    getFAQsByCategory(category: FAQCategory): Promise<FAQDocument[]>;
+    getHomepageFAQs(): Promise<FAQDocument[]>;
+    getFooterFAQs(): Promise<FAQDocument[]>;
+    getPinnedFAQs(category?: FAQCategory): Promise<FAQDocument[]>;
+    searchByTag(tag: string): Promise<FAQDocument[]>;
+    getMostHelpful(limit?: number): Promise<FAQDocument[]>;
+    interpolateVariables(faq: FAQDocument, variables?: Record<string, string | number>): Promise<FAQWithInterpolatedAnswer>;
+    incrementViews(faqId: string): Promise<void>;
+    markHelpful(faqId: string): Promise<void>;
+    markNotHelpful(faqId: string): Promise<void>;
+    createWithSlug(input: FAQCreateInput): Promise<FAQDocument>;
+    getRelatedFAQs(faqId: string): Promise<FAQDocument[]>;
+}
+export declare const faqsRepository: FirebaseFAQsRepository;

package/dist/features/faq/repository/faqs.repository.js

@@ -0,0 +1,299 @@
+import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
+import { DatabaseError } from "../../../errors";
+import { increment } from "../../../contracts/field-ops";
+import { FAQS_COLLECTION, createFAQId, slugifyQuestion, } from "../schemas";
+export class FAQsRepository {
+    constructor(repo) {
+        this.repo = repo;
+    }
+    async findAll(query) {
+        const base = { filters: "isActive==true", ...query };
+        if (query?.filters) {
+            base.filters = `isActive==true,${query.filters}`;
+        }
+        return this.repo.findAll(base);
+    }
+    async findByCategory(category) {
+        const result = await this.repo.findAll({
+            filters: `isActive==true,category==${category}`,
+            sort: "order",
+            perPage: 100,
+        });
+        return result.data;
+    }
+    async findForHomepage() {
+        const result = await this.repo.findAll({
+            filters: "isActive==true,showOnHomepage==true",
+            sort: "priority",
+            perPage: 10,
+        });
+        return result.data;
+    }
+    async findForFooter() {
+        const result = await this.repo.findAll({
+            filters: "isActive==true,showInFooter==true",
+            sort: "order",
+            perPage: 20,
+        });
+        return result.data;
+    }
+    async findById(id) {
+        return this.repo.findById(id);
+    }
+    async create(data) {
+        return this.repo.create(data);
+    }
+    async update(id, data) {
+        return this.repo.update(id, data);
+    }
+    async delete(id) {
+        return this.repo.delete(id);
+    }
+}
+export class FirebaseFAQsRepository extends BaseRepository {
+    constructor() {
+        super(FAQS_COLLECTION);
+    }
+    buildSearchTokens(input) {
+        const rawText = [
+            input.question,
+            typeof input.answer === "string" ? input.answer : input.answer?.text,
+            input.category,
+            ...(input.tags ?? []),
+        ]
+            .filter(Boolean)
+            .join(" ")
+            .toLowerCase();
+        return Array.from(new Set(rawText
+            .split(/[^a-z0-9]+/i)
+            .map((token) => token.trim())
+            .filter((token) => token.length >= 2))).slice(0, 50);
+    }
+    async create(data) {
+        const searchTokens = this.buildSearchTokens({
+            question: data.question ?? "",
+            answer: data.answer ?? {
+                text: "",
+                format: "plain",
+            },
+            tags: data.tags ?? [],
+            category: (data.category ?? "general"),
+        });
+        return super.create({
+            ...data,
+            searchTokens,
+        });
+    }
+    async update(id, data) {
+        const current = await this.findById(id);
+        if (!current) {
+            throw new DatabaseError(`Failed to update FAQ: missing document ${id}`);
+        }
+        const merged = {
+            ...current,
+            ...data,
+        };
+        return super.update(id, {
+            ...data,
+            searchTokens: this.buildSearchTokens({
+                question: merged.question,
+                answer: merged.answer,
+                tags: merged.tags ?? [],
+                category: merged.category,
+            }),
+        });
+    }
+    async list(model, opts) {
+        let baseQuery = this.getCollection();
+        const tags = opts?.tags?.filter(Boolean) ?? [];
+        const searchTokens = (opts?.search ?? "")
+            .toLowerCase()
+            .split(/[^a-z0-9]+/i)
+            .map((token) => token.trim())
+            .filter((token) => token.length >= 2)
+            .slice(0, 10);
+        if (tags.length > 0 && searchTokens.length > 0) {
+            throw new DatabaseError("Combining FAQ tag filters and token search requires a dedicated search index");
+        }
+        if (tags.length === 1) {
+            baseQuery = baseQuery.where("tags", "array-contains", tags[0]);
+        }
+        else if (tags.length > 1) {
+            baseQuery = baseQuery.where("tags", "array-contains-any", tags.slice(0, 10));
+        }
+        if (searchTokens.length === 1) {
+            baseQuery = baseQuery.where("searchTokens", "array-contains", searchTokens[0]);
+        }
+        else if (searchTokens.length > 1) {
+            baseQuery = baseQuery.where("searchTokens", "array-contains-any", searchTokens);
+        }
+        return this.sieveQuery(model, FirebaseFAQsRepository.SIEVE_FIELDS, { baseQuery });
+    }
+    async getFAQBySlug(slug) {
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where("seo.slug", "==", slug)
+            .limit(1)
+            .get();
+        if (snapshot.empty)
+            return null;
+        return this.mapDoc(snapshot.docs[0]);
+    }
+    async getFAQsByCategory(category) {
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where("category", "==", category)
+            .where("isActive", "==", true)
+            .orderBy("order", "asc")
+            .get();
+        return snapshot.docs.map((doc) => this.mapDoc(doc));
+    }
+    async getHomepageFAQs() {
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where("showOnHomepage", "==", true)
+            .where("isActive", "==", true)
+            .orderBy("priority", "desc")
+            .get();
+        return snapshot.docs.map((doc) => this.mapDoc(doc));
+    }
+    async getFooterFAQs() {
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where("showInFooter", "==", true)
+            .where("isActive", "==", true)
+            .orderBy("order", "asc")
+            .get();
+        return snapshot.docs.map((doc) => this.mapDoc(doc));
+    }
+    async getPinnedFAQs(category) {
+        let query = this.db
+            .collection(this.collection)
+            .where("isPinned", "==", true)
+            .where("isActive", "==", true);
+        if (category) {
+            query = query.where("category", "==", category);
+        }
+        const snapshot = await query.orderBy("order", "asc").get();
+        return snapshot.docs.map((doc) => this.mapDoc(doc));
+    }
+    async searchByTag(tag) {
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where("tags", "array-contains", tag)
+            .where("isActive", "==", true)
+            .get();
+        return snapshot.docs.map((doc) => this.mapDoc(doc));
+    }
+    async getMostHelpful(limit = 10) {
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where("isActive", "==", true)
+            .orderBy("stats.helpful", "desc")
+            .limit(limit)
+            .get();
+        return snapshot.docs.map((doc) => this.mapDoc(doc));
+    }
+    async interpolateVariables(faq, variables) {
+        const allVariables = variables ?? {};
+        let interpolatedText = faq.answer.text;
+        const regex = /\{\{(\w+)\}\}/g;
+        const placeholders = Array.from(interpolatedText.matchAll(regex), (m) => m[1]);
+        for (const variableName of placeholders) {
+            const value = allVariables[variableName] ?? faq.variables?.[variableName];
+            if (value !== undefined) {
+                interpolatedText = interpolatedText.replace(new RegExp(`\\{\\{${variableName}\\}\\}`, "g"), String(value));
+            }
+        }
+        return {
+            ...faq,
+            answer: {
+                ...faq.answer,
+                interpolated: interpolatedText,
+            },
+        };
+    }
+    async incrementViews(faqId) {
+        await this.db
+            .collection(this.collection)
+            .doc(faqId)
+            .update({
+            "stats.views": increment(1),
+            "stats.lastViewed": new Date(),
+        });
+    }
+    async markHelpful(faqId) {
+        await this.db
+            .collection(this.collection)
+            .doc(faqId)
+            .update({
+            "stats.helpful": increment(1),
+        });
+    }
+    async markNotHelpful(faqId) {
+        await this.db
+            .collection(this.collection)
+            .doc(faqId)
+            .update({
+            "stats.notHelpful": increment(1),
+        });
+    }
+    async createWithSlug(input) {
+        const slug = input.seo?.slug?.trim() || slugifyQuestion(input.question);
+        const id = createFAQId(input.category, input.question);
+        const faqData = {
+            ...input,
+            seo: {
+                ...input.seo,
+                slug,
+            },
+            searchTokens: this.buildSearchTokens({
+                question: input.question,
+                answer: input.answer,
+                tags: input.tags ?? [],
+                category: input.category,
+            }),
+            stats: {
+                views: 0,
+                helpful: 0,
+                notHelpful: 0,
+            },
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+        await this.db
+            .collection(this.collection)
+            .doc(id)
+            .set(prepareForFirestore(faqData));
+        return { id, ...faqData };
+    }
+    async getRelatedFAQs(faqId) {
+        const faq = await this.findById(faqId);
+        if (!faq || !faq.relatedFAQs || faq.relatedFAQs.length === 0) {
+            return [];
+        }
+        const relatedFAQs = [];
+        for (const relatedId of faq.relatedFAQs) {
+            const relatedFAQ = await this.findById(relatedId);
+            if (relatedFAQ && relatedFAQ.isActive) {
+                relatedFAQs.push(relatedFAQ);
+            }
+        }
+        return relatedFAQs;
+    }
+}
+FirebaseFAQsRepository.SIEVE_FIELDS = {
+    question: { canFilter: true, canSort: true },
+    category: { canFilter: true, canSort: true },
+    isActive: { canFilter: true, canSort: false },
+    showOnHomepage: { canFilter: true, canSort: false },
+    showInFooter: { canFilter: true, canSort: false },
+    isPinned: { canFilter: true, canSort: false },
+    order: { canFilter: true, canSort: true },
+    priority: { canFilter: true, canSort: true },
+    tags: { canFilter: true, canSort: false },
+    searchTokens: { canFilter: true, canSort: false },
+    "stats.helpful": { canFilter: false, canSort: true },
+    createdAt: { canFilter: true, canSort: true },
+};
+export const faqsRepository = new FirebaseFAQsRepository();

package/dist/features/faq/schemas/firestore.d.ts

@@ -0,0 +1,63 @@
+/**
+ * FAQ Feature Firestore Document Types & Constants
+ */
+import type { FAQCategory, FAQAnswer, FAQStats } from "../types";
+export type { FAQCategory, FAQAnswer, FAQStats } from "../types";
+export interface FAQSEO {
+    slug: string;
+    metaTitle?: string;
+    metaDescription?: string;
+}
+export interface FAQDocument {
+    id: string;
+    question: string;
+    answer: FAQAnswer;
+    category: FAQCategory;
+    showOnHomepage: boolean;
+    showInFooter: boolean;
+    isPinned: boolean;
+    order: number;
+    priority: number;
+    tags: string[];
+    searchTokens?: string[];
+    relatedFAQs: string[];
+    useSiteSettings: boolean;
+    variables?: Record<string, string>;
+    stats: Required<FAQStats> & {
+        lastViewed?: Date;
+    };
+    seo: FAQSEO;
+    isActive: boolean;
+    createdBy: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export declare const FAQS_COLLECTION: "faqs";
+export declare const FAQS_INDEXED_FIELDS: readonly ["seo.slug", "category", "order", "showOnHomepage", "showInFooter", "isPinned", "priority", "tags", "searchTokens", "isActive", "stats.helpful", "createdBy", "createdAt"];
+export declare const FAQ_CATEGORY_LABELS: Record<FAQCategory, string>;
+export declare const DEFAULT_FAQ_DATA: Partial<FAQDocument>;
+export declare const FAQS_PUBLIC_FIELDS: readonly ["id", "question", "answer", "category", "showOnHomepage", "showInFooter", "isPinned", "order", "priority", "tags", "relatedFAQs", "stats.views", "stats.helpful", "stats.notHelpful", "seo.slug", "seo.metaTitle", "seo.metaDescription", "isActive", "createdAt"];
+export type FAQCreateInput = Omit<FAQDocument, "id" | "createdAt" | "updatedAt" | "stats">;
+export type FAQUpdateInput = Partial<Pick<FAQDocument, "question" | "answer" | "category" | "showOnHomepage" | "showInFooter" | "isPinned" | "order" | "priority" | "tags" | "relatedFAQs" | "useSiteSettings" | "variables" | "seo" | "isActive">>;
+export interface FAQWithInterpolatedAnswer extends Omit<FAQDocument, "answer"> {
+    answer: FAQAnswer & {
+        interpolated: string;
+    };
+}
+export declare const faqQueryHelpers: {
+    readonly bySlug: (slug: string) => readonly ["seo.slug", "==", string];
+    readonly byCategory: (category: FAQCategory) => readonly ["category", "==", FAQCategory];
+    readonly homepage: () => readonly ["showOnHomepage", "==", true];
+    readonly footer: () => readonly ["showInFooter", "==", true];
+    readonly pinned: () => readonly ["isPinned", "==", true];
+    readonly active: () => readonly ["isActive", "==", true];
+    readonly byTag: (tag: string) => readonly ["tags", "array-contains", string];
+    readonly byCreator: (userId: string) => readonly ["createdBy", "==", string];
+};
+export declare function extractVariablePlaceholders(text: string): string[];
+export declare function usesVariableInterpolation(faq: FAQDocument): boolean;
+export declare function validateFAQVariables(faq: FAQDocument, siteSettingsVariables: Record<string, string | number>): string[];
+export declare function isPopularFAQ(faq: FAQDocument): boolean;
+export declare function getHelpfulnessPercentage(faq: FAQDocument): number;
+export declare function slugifyQuestion(question: string): string;
+export declare function createFAQId(category: FAQCategory, question: string): string;

package/dist/features/faq/schemas/firestore.js

@@ -0,0 +1,115 @@
+/**
+ * FAQ Feature Firestore Document Types & Constants
+ */
+import { generateFAQId } from "../../../utils/id-generators";
+export const FAQS_COLLECTION = "faqs";
+export const FAQS_INDEXED_FIELDS = [
+    "seo.slug",
+    "category",
+    "order",
+    "showOnHomepage",
+    "showInFooter",
+    "isPinned",
+    "priority",
+    "tags",
+    "searchTokens",
+    "isActive",
+    "stats.helpful",
+    "createdBy",
+    "createdAt",
+];
+export const FAQ_CATEGORY_LABELS = {
+    orders_payment: "Orders & Payment",
+    shipping_delivery: "Shipping & Delivery",
+    returns_refunds: "Returns & Refunds",
+    product_information: "Product Information",
+    account_security: "Account & Security",
+    technical_support: "Technical Support",
+    general: "General Questions",
+};
+export const DEFAULT_FAQ_DATA = {
+    showOnHomepage: false,
+    showInFooter: false,
+    isPinned: false,
+    order: 0,
+    priority: 0,
+    tags: [],
+    searchTokens: [],
+    relatedFAQs: [],
+    useSiteSettings: true,
+    variables: {},
+    stats: { views: 0, helpful: 0, notHelpful: 0 },
+    isActive: true,
+};
+export const FAQS_PUBLIC_FIELDS = [
+    "id",
+    "question",
+    "answer",
+    "category",
+    "showOnHomepage",
+    "showInFooter",
+    "isPinned",
+    "order",
+    "priority",
+    "tags",
+    "relatedFAQs",
+    "stats.views",
+    "stats.helpful",
+    "stats.notHelpful",
+    "seo.slug",
+    "seo.metaTitle",
+    "seo.metaDescription",
+    "isActive",
+    "createdAt",
+];
+export const faqQueryHelpers = {
+    bySlug: (slug) => ["seo.slug", "==", slug],
+    byCategory: (category) => ["category", "==", category],
+    homepage: () => ["showOnHomepage", "==", true],
+    footer: () => ["showInFooter", "==", true],
+    pinned: () => ["isPinned", "==", true],
+    active: () => ["isActive", "==", true],
+    byTag: (tag) => ["tags", "array-contains", tag],
+    byCreator: (userId) => ["createdBy", "==", userId],
+};
+export function extractVariablePlaceholders(text) {
+    const regex = /\{\{(\w+)\}\}/g;
+    return Array.from(text.matchAll(regex), (m) => m[1]);
+}
+export function usesVariableInterpolation(faq) {
+    if (!faq.useSiteSettings)
+        return false;
+    return extractVariablePlaceholders(faq.answer.text).length > 0;
+}
+export function validateFAQVariables(faq, siteSettingsVariables) {
+    if (!faq.useSiteSettings)
+        return [];
+    const placeholders = extractVariablePlaceholders(faq.answer.text);
+    const available = { ...siteSettingsVariables, ...(faq.variables || {}) };
+    return placeholders.filter((v) => !(v in available));
+}
+export function isPopularFAQ(faq) {
+    const { views, helpful, notHelpful } = faq.stats;
+    const total = helpful + notHelpful;
+    const ratio = total > 0 ? helpful / total : 0;
+    return views >= 100 && ratio >= 0.7;
+}
+export function getHelpfulnessPercentage(faq) {
+    const { helpful, notHelpful } = faq.stats;
+    const total = helpful + notHelpful;
+    if (total === 0)
+        return 0;
+    return Math.round((helpful / total) * 100);
+}
+export function slugifyQuestion(question) {
+    return question
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/[\s_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}
+export function createFAQId(category, question) {
+    return generateFAQId({ category, question });
+}