@mohasinac/appkit 2.3.1 → 2.4.0

package/dist/features/auctions/hooks/useAuctions.js

@@ -25,6 +25,7 @@ export function useAuctions(params = {}, opts) {
         queryFn: () => apiClient.get(`${endpoint}${qs ? `?${qs}` : ""}`),
         enabled: opts?.enabled ?? true,
         initialData: opts?.initialData,
+        staleTime: opts?.staleTime ?? (opts?.initialData !== undefined ? Infinity : 0),
     });
     return {
         data,

package/dist/features/auctions/schemas/index.d.ts

@@ -26,16 +26,22 @@ export declare const auctionItemSchema: z.ZodObject<{
         type: z.ZodEnum<["image", "video", "file"]>;
         alt: z.ZodOptional<z.ZodString>;
         thumbnailUrl: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodEnum<["upload", "youtube", "external"]>>;
+        youtubeId: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         url: string;
         type: "video" | "image" | "file";
+        source?: "external" | "upload" | "youtube" | undefined;
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
+        youtubeId?: string | undefined;
     }, {
         url: string;
         type: "video" | "image" | "file";
+        source?: "external" | "upload" | "youtube" | undefined;
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
+        youtubeId?: string | undefined;
     }>, "many">>;
     currency: z.ZodString;
     price: z.ZodNumber;
@@ -57,11 +63,11 @@ export declare const auctionItemSchema: z.ZodObject<{
     status: "draft" | "published" | "archived" | "sold";
     createdAt: string;
     updatedAt: string;
-    sellerId: string;
+    price: number;
     currency: string;
     slug: string;
+    sellerId: string;
     featured: boolean;
-    price: number;
     isAuction: true;
     startingBid: number;
     bidCount: number;
@@ -69,26 +75,28 @@ export declare const auctionItemSchema: z.ZodObject<{
     media?: {
         url: string;
         type: "video" | "image" | "file";
+        source?: "external" | "upload" | "youtube" | undefined;
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
+        youtubeId?: string | undefined;
     }[] | undefined;
+    storeId?: string | undefined;
     images?: string[] | undefined;
     description?: string | undefined;
-    storeSlug?: string | undefined;
-    storeId?: string | undefined;
     mainImage?: string | undefined;
     currentBid?: number | undefined;
+    storeSlug?: string | undefined;
 }, {
     id: string;
     title: string;
     status: "draft" | "published" | "archived" | "sold";
     createdAt: string;
     updatedAt: string;
-    sellerId: string;
+    price: number;
     currency: string;
     slug: string;
+    sellerId: string;
     featured: boolean;
-    price: number;
     isAuction: true;
     startingBid: number;
     bidCount: number;
@@ -96,15 +104,17 @@ export declare const auctionItemSchema: z.ZodObject<{
     media?: {
         url: string;
         type: "video" | "image" | "file";
+        source?: "external" | "upload" | "youtube" | undefined;
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
+        youtubeId?: string | undefined;
     }[] | undefined;
+    storeId?: string | undefined;
     images?: string[] | undefined;
     description?: string | undefined;
-    storeSlug?: string | undefined;
-    storeId?: string | undefined;
     mainImage?: string | undefined;
     currentBid?: number | undefined;
+    storeSlug?: string | undefined;
 }>;
 export declare const bidRecordSchema: z.ZodObject<{
     id: z.ZodString;

package/dist/features/auth/actions/profile-actions.d.ts

@@ -5,6 +5,7 @@
  * Auth, rate-limiting, and Next.js specifics are handled by the consumer.
  */
 import type { UserDocument } from "../schemas";
+import type { Review } from "../../reviews/types";
 export type UpdateProfileInput = {
     displayName?: string;
     email?: string;
@@ -22,6 +23,7 @@ export type UpdateProfileInput = {
 export declare function updateUserProfile(userId: string, input: UpdateProfileInput): Promise<UserDocument>;
 export declare function getUserProfile(userId: string): Promise<UserDocument | null>;
 export declare function getUserSessions(userId: string): Promise<import("..").SessionDocument[]>;
-export declare function getPublicUserProfile(userId: string): Promise<Pick<UserDocument, "id" | "displayName" | "photoURL" | "role" | "createdAt"> | null>;
-export declare function getSellerReviews(sellerId: string): Promise<import("../../reviews").ReviewDocument[]>;
-export declare function getSellerProducts(sellerId: string): Promise<import("../../products").ProductDocument[]>;
+export declare function getPublicUserProfile(userId: string): Promise<Pick<UserDocument, "id" | "displayName" | "photoURL" | "role" | "createdAt" | "storeId" | "storeSlug" | "publicProfile" | "stats"> | null>;
+/** Fetch approved reviews for a store. storeId === storeSlug in this project. */
+export declare function getSellerReviews(storeId: string): Promise<Review[]>;
+export declare function getProfileStoreProducts(storeId: string): Promise<import("../../products").ProductDocument[]>;

package/dist/features/auth/actions/profile-actions.js

@@ -32,19 +32,38 @@ export async function getPublicUserProfile(userId) {
         photoURL: user.photoURL,
         role: user.role,
         createdAt: user.createdAt,
+        storeId: user.storeId,
+        storeSlug: user.storeSlug,
+        publicProfile: user.publicProfile,
+        stats: user.stats,
     };
 }
-export async function getSellerReviews(sellerId) {
-    const products = await productRepository.findBySeller(sellerId);
-    const published = products.filter((p) => p.status === ProductStatusValues.PUBLISHED);
-    if (published.length === 0)
-        return [];
-    const batches = await Promise.all(published
-        .slice(0, 20)
-        .map((p) => reviewRepository.findApprovedByProduct(p.id).catch(() => [])));
-    return batches.flat().map(maskPublicReview);
+/** Fetch approved reviews for a store. storeId === storeSlug in this project. */
+export async function getSellerReviews(storeId) {
+    const snapshot = await reviewRepository.findApprovedByStore(storeId).catch(() => []);
+    return snapshot.map((r) => ({
+        id: r.id,
+        productId: r.productId,
+        productTitle: r.productTitle,
+        userId: r.userId,
+        userName: maskPublicReview(r).userName,
+        userAvatar: r.userAvatar,
+        rating: r.rating,
+        title: r.title,
+        comment: r.comment,
+        images: r.images?.map((url) => ({ url })),
+        status: r.status,
+        helpfulCount: r.helpfulCount,
+        reportCount: r.reportCount,
+        verified: r.verified,
+        featured: r.featured,
+        createdAt: r.createdAt instanceof Date ? r.createdAt.toISOString() : undefined,
+        updatedAt: r.updatedAt instanceof Date ? r.updatedAt.toISOString() : undefined,
+        storeSlug: r.storeId,
+        storeName: r.storeName,
+    }));
 }
-export async function getSellerProducts(sellerId) {
-    const products = await productRepository.findBySeller(sellerId);
+export async function getProfileStoreProducts(storeId) {
+    const products = await productRepository.findByStore(storeId);
     return products.filter((p) => p.status === ProductStatusValues.PUBLISHED);
 }

package/dist/features/auth/auth-helpers.js

@@ -2,6 +2,7 @@ import { getTokenTimeRemaining, isTokenExpired } from "./token-helpers";
 const ROLE_HIERARCHY = {
     user: 0,
     seller: 1,
+    employee: 2,
     moderator: 2,
     admin: 3,
 };

package/dist/features/auth/components/LoginForm.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useState } from "react";
 import { Alert, Div, Heading, Row, Text, Label } from "../../../ui";
+import { SocialAuthButtons } from "./SocialAuthButtons";
 export function LoginForm({ onSubmit, onGoogleLogin, isLoading = false, error, labels = {}, renderSocialButtons, renderCreateAccountLink, renderForgotPasswordLink, renderSubmitButton, className = "", }) {
     const [values, setValues] = useState({
         email: "",
@@ -14,5 +15,5 @@ export function LoginForm({ onSubmit, onGoogleLogin, isLoading = false, error, l
     }, [onSubmit, values]);
     return (_jsx(Div, { className: `flex items-center justify-center min-h-[60vh] px-4 ${className}`, children: _jsxs(Div, { className: "max-w-md w-full space-y-6", children: [_jsxs(Div, { className: "text-center", children: [_jsx(Heading, { level: 1, className: "text-3xl font-extrabold", children: labels.title ?? "Sign In" }), (labels.subtitle || renderCreateAccountLink) && (_jsxs(Text, { className: "mt-2 text-sm text-neutral-600", children: [labels.subtitle ?? "Or", " ", renderCreateAccountLink?.()] }))] }), error && (_jsx(Alert, { variant: "error", compact: true, children: error })), _jsxs("form", { className: "space-y-4", onSubmit: handleSubmit, noValidate: true, children: [_jsxs(Div, { children: [_jsx(Label, { htmlFor: "login-email", className: "block text-sm font-medium mb-1", children: labels.emailLabel ?? "Email address" }), _jsx("input", { id: "login-email", name: "email", type: "email", autoComplete: "username", required: true, placeholder: labels.emailPlaceholder ?? "you@example.com", value: values.email, onChange: (e) => setValues({ ...values, email: e.target.value }), className: "w-full rounded-lg border border-neutral-300 dark:border-slate-700 bg-white dark:bg-slate-900 text-zinc-900 dark:text-zinc-50 placeholder:text-neutral-400 dark:placeholder:text-slate-500 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs(Div, { children: [_jsx(Label, { htmlFor: "login-password", className: "block text-sm font-medium mb-1", children: labels.passwordLabel ?? "Password" }), _jsx("input", { id: "login-password", name: "password", type: "password", autoComplete: "current-password", required: true, placeholder: labels.passwordPlaceholder ?? "••••••••", value: values.password, onChange: (e) => setValues({ ...values, password: e.target.value }), className: "w-full rounded-lg border border-neutral-300 dark:border-slate-700 bg-white dark:bg-slate-900 text-zinc-900 dark:text-zinc-50 placeholder:text-neutral-400 dark:placeholder:text-slate-500 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs(Row, { justify: "between", children: [_jsxs(Row, { className: "gap-2", children: [_jsx("input", { id: "login-remember", type: "checkbox", checked: values.rememberMe ?? false, onChange: (e) => setValues({ ...values, rememberMe: e.target.checked }), className: "h-4 w-4 rounded border-neutral-300 dark:border-slate-600 accent-primary" }), _jsx(Label, { htmlFor: "login-remember", className: "text-sm", children: labels.rememberMe ?? "Remember me" })] }), renderForgotPasswordLink?.()] }), renderSubmitButton ? (renderSubmitButton(isLoading, labels)) : (_jsx("button", { type: "submit", disabled: isLoading, className: "w-full rounded-lg bg-primary px-4 py-2.5 text-sm font-semibold text-white disabled:opacity-60 hover:bg-primary/90 transition-colors", children: isLoading
                                 ? (labels.submittingLabel ?? "Signing in…")
-                                : (labels.submitLabel ?? "Sign in") }))] }), renderSocialButtons?.()] }) }));
+                                : (labels.submitLabel ?? "Sign in") }))] }), onGoogleLogin && !renderSocialButtons ? (_jsx(SocialAuthButtons, { onGoogle: onGoogleLogin, disabled: isLoading, dividerLabel: labels.orSeparator ?? "Or continue with", googleLabel: "Sign in with Google" })) : (renderSocialButtons?.())] }) }));
 }

package/dist/features/auth/hooks/useAuth.js

@@ -2,6 +2,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import { getClientAuthProvider } from "../../../contracts/client-auth";
+import { getClientSessionAdapter } from "../../../contracts/client-session";
 import { apiClient } from "../../../http";
 import { useAuthEvent } from "./useAuthEvent";
 import { RealtimeEventStatus } from "../../../react/hooks/useRealtimeEvent";
@@ -32,11 +33,15 @@ export function useCurrentUser(opts) {
 export function useLogin(options) {
     return useMutation({
         mutationFn: async (credentials) => {
-            await apiClient.post(AUTH_ENDPOINTS.LOGIN, {
-                email: credentials.email.trim(),
-                password: credentials.password,
-            });
+            // Client Firebase SDK authenticates first (handles password verification)
             await getClientAuthProvider().signInWithEmailAndPassword(credentials.email.trim(), credentials.password);
+            // Exchange the fresh ID token for a server-side session cookie
+            const currentUser = getClientSessionAdapter().getCurrentUser();
+            if (!currentUser) {
+                throw new Error("Sign-in succeeded but no current user found.");
+            }
+            const idToken = await currentUser.getIdToken(true);
+            await apiClient.post(AUTH_ENDPOINTS.SESSION, { idToken });
             return { success: true };
         },
         onSuccess: options?.onSuccess,
@@ -99,13 +104,20 @@ export function useGoogleLogin(options) {
 export function useRegister(options) {
     return useMutation({
         mutationFn: async (data) => {
+            // Create the user account on the server
             const response = await apiClient.post(AUTH_ENDPOINTS.REGISTER, {
                 email: data.email.trim(),
                 password: data.password,
                 displayName: data.displayName?.trim() || "",
                 acceptTerms: data.acceptTerms,
             });
+            // Sign in via client SDK and exchange ID token for a server session cookie
             await getClientAuthProvider().signInWithEmailAndPassword(data.email.trim(), data.password);
+            const currentUser = getClientSessionAdapter().getCurrentUser();
+            if (currentUser) {
+                const idToken = await currentUser.getIdToken(true);
+                await apiClient.post(AUTH_ENDPOINTS.SESSION, { idToken });
+            }
             return { success: true, ...response };
         },
         onSuccess: options?.onSuccess,

package/dist/features/auth/permissions/constants.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Permission & Role-Based Access Control Constants
+ *
+ * Single source of truth for all Permission strings, EmployeeGroup presets,
+ * PERMISSION_GROUPS bundles, and StoreCapability flags.
+ *
+ * Design: admin role bypasses all permission checks. employee role is gated
+ * entirely by the permissions[] field on their UserDocument. Roles are convenience
+ * bundles — individual employees can have custom overrides on top of their preset.
+ *
+ * Permission naming: admin:resource:action
+ * Ban action naming: plain verb phrase — write_reviews, place_bids, etc.
+ */
+export type Permission = "admin:dashboard:view" | "admin:users:read" | "admin:users:write" | "admin:users:delete" | "admin:user-bans:read" | "admin:user-bans:write" | "admin:products:read" | "admin:products:write" | "admin:products:delete" | "admin:orders:read" | "admin:orders:write" | "admin:returns:read" | "admin:returns:write" | "admin:stores:read" | "admin:stores:write" | "admin:store-addresses:read" | "admin:analytics:view" | "admin:payouts:read" | "admin:payouts:write" | "admin:categories:read" | "admin:categories:write" | "admin:categories:delete" | "admin:brands:read" | "admin:brands:write" | "admin:brands:delete" | "admin:coupons:read" | "admin:coupons:write" | "admin:coupons:delete" | "admin:deals:read" | "admin:deals:write" | "admin:featured:read" | "admin:featured:write" | "admin:reviews:read" | "admin:reviews:write" | "admin:reviews:delete" | "admin:blog:read" | "admin:blog:write" | "admin:blog:delete" | "admin:blog:publish" | "admin:bids:read" | "admin:bids:write" | "admin:media:read" | "admin:media:write" | "admin:media:delete" | "admin:site:read" | "admin:site:write" | "admin:navigation:read" | "admin:navigation:write" | "admin:sections:read" | "admin:sections:write" | "admin:carousel:read" | "admin:carousel:write" | "admin:carousel:delete" | "admin:ads:read" | "admin:ads:write" | "admin:ads:delete" | "admin:faqs:read" | "admin:faqs:write" | "admin:faqs:delete" | "admin:newsletter:read" | "admin:newsletter:write" | "admin:contact:read" | "admin:events:read" | "admin:events:write" | "admin:events:delete" | "admin:event-entries:read" | "admin:event-entries:write" | "admin:support-tickets:read" | "admin:support-tickets:write" | "admin:support-tickets:assign" | "admin:support-tickets:close" | "admin:scammers:read" | "admin:scammers:write" | "admin:scammers:verify" | "admin:scammers:delete" | "admin:sessions:read" | "admin:sessions:delete" | "admin:notifications:read" | "admin:notifications:write" | "admin:carts:read" | "admin:wishlists:read" | "admin:feature-flags:read" | "admin:feature-flags:write" | "admin:copilot:view" | "admin:team:read" | "admin:team:write";
+/**
+ * Granular user actions that can be soft-banned individually.
+ * A user may have multiple simultaneous soft bans of different types.
+ * Hard ban (disabled: true) overrides all of these.
+ */
+export type BannedAction = "write_reviews" | "write_blog_comments" | "join_events" | "place_bids" | "create_listings" | "send_messages" | "create_support_tickets" | "report_scammers";
+/**
+ * Preset permission bundles. "custom" = no preset, permissions set individually.
+ * Used for display and for pre-filling the permissions editor when inviting employees.
+ */
+export type EmployeeGroup = "content_moderator" | "review_manager" | "blog_poster" | "community_manager" | "event_handler" | "newsletter_manager" | "seo_manager" | "ad_manager" | "site_manager" | "catalog_manager" | "finance_manager" | "data_analyst" | "customer_support" | "support_agent" | "store_onboarding" | "trust_and_safety" | "auction_monitor" | "scam_moderator" | "custom";
+/**
+ * Pre-defined permission bundles for each EmployeeGroup.
+ * Admin always bypasses; these bundles are only relevant for role=employee.
+ */
+export declare const PERMISSION_GROUPS: Record<Exclude<EmployeeGroup, "custom">, Permission[]>;
+/**
+ * Maps each /admin/[section] pathname prefix to the permission required to READ it.
+ * Write/delete operations use the corresponding write/delete permission at the API level.
+ * Admin role bypasses this map entirely.
+ */
+export declare const ROUTE_PERMISSION_MAP: Record<string, Permission>;
+/**
+ * Per-store feature flags stored as capabilities[] on StoreDocument.
+ * Managed by admin via AdminStoreEditorView.
+ * Checked server-side on store API routes — client check is UX only.
+ *
+ * Defaults on store creation: ["suggest_brands", "create_coupons"]
+ */
+export type StoreCapability = "host_auctions" | "host_preorders" | "create_categories" | "suggest_brands" | "create_coupons" | "bulk_listing_import" | "extended_return_window" | "verified_seller" | "featured_placement" | "promotional_banner" | "priority_support" | "multiple_stores" | "custom_store_slug" | "api_access" | "lower_commission_rate" | "early_access_features" | "advanced_analytics" | "whatsapp_catalog_sync";
+/** Default capabilities granted to every new store on creation. */
+export declare const DEFAULT_STORE_CAPABILITIES: StoreCapability[];
+/**
+ * Check whether a permission array includes a required permission.
+ * Use server-side only — never trust client-supplied permission arrays.
+ */
+export declare function hasPermission(permissions: Permission[], required: Permission): boolean;
+/**
+ * Check whether a permission array includes ANY of the required permissions.
+ */
+export declare function hasAnyPermission(permissions: Permission[], required: Permission[]): boolean;
+/**
+ * Check whether a permission array includes ALL of the required permissions.
+ */
+export declare function hasAllPermissions(permissions: Permission[], required: Permission[]): boolean;
+/**
+ * Check whether a store's capabilities include a specific capability.
+ */
+export declare function hasCapability(capabilities: StoreCapability[], required: StoreCapability): boolean;

package/dist/features/auth/permissions/constants.js

@@ -0,0 +1,323 @@
+/**
+ * Permission & Role-Based Access Control Constants
+ *
+ * Single source of truth for all Permission strings, EmployeeGroup presets,
+ * PERMISSION_GROUPS bundles, and StoreCapability flags.
+ *
+ * Design: admin role bypasses all permission checks. employee role is gated
+ * entirely by the permissions[] field on their UserDocument. Roles are convenience
+ * bundles — individual employees can have custom overrides on top of their preset.
+ *
+ * Permission naming: admin:resource:action
+ * Ban action naming: plain verb phrase — write_reviews, place_bids, etc.
+ */
+// ============================================================================
+// PERMISSION GROUP PRESETS
+// ============================================================================
+/**
+ * Pre-defined permission bundles for each EmployeeGroup.
+ * Admin always bypasses; these bundles are only relevant for role=employee.
+ */
+export const PERMISSION_GROUPS = {
+    content_moderator: [
+        "admin:dashboard:view",
+        "admin:reviews:read",
+        "admin:reviews:write",
+        "admin:reviews:delete",
+        "admin:products:read",
+        "admin:users:read",
+        "admin:blog:read",
+    ],
+    review_manager: [
+        "admin:dashboard:view",
+        "admin:reviews:read",
+        "admin:reviews:write",
+        "admin:reviews:delete",
+        "admin:products:read",
+        "admin:users:read",
+    ],
+    blog_poster: [
+        "admin:dashboard:view",
+        "admin:blog:read",
+        "admin:blog:write",
+        // NOT blog:delete or blog:publish — junior writer only
+        "admin:media:read",
+        "admin:media:write",
+    ],
+    community_manager: [
+        "admin:dashboard:view",
+        "admin:events:read",
+        "admin:events:write",
+        "admin:events:delete",
+        "admin:event-entries:read",
+        "admin:event-entries:write",
+        "admin:blog:read",
+        "admin:blog:write",
+        "admin:blog:publish",
+        "admin:reviews:read",
+        "admin:notifications:read",
+        "admin:notifications:write",
+        "admin:newsletter:read",
+        "admin:newsletter:write",
+        "admin:media:read",
+        "admin:media:write",
+    ],
+    event_handler: [
+        "admin:dashboard:view",
+        "admin:events:read",
+        "admin:events:write",
+        "admin:events:delete",
+        "admin:event-entries:read",
+        "admin:event-entries:write",
+        "admin:notifications:read",
+        "admin:notifications:write",
+    ],
+    newsletter_manager: [
+        "admin:dashboard:view",
+        "admin:newsletter:read",
+        "admin:newsletter:write",
+        "admin:contact:read",
+        "admin:users:read",
+    ],
+    seo_manager: [
+        "admin:dashboard:view",
+        "admin:faqs:read",
+        "admin:faqs:write",
+        "admin:faqs:delete",
+        "admin:blog:read",
+        "admin:blog:write",
+        "admin:blog:publish",
+        "admin:navigation:read",
+        "admin:navigation:write",
+        "admin:sections:read",
+        "admin:sections:write",
+        "admin:site:read",
+    ],
+    ad_manager: [
+        "admin:dashboard:view",
+        "admin:ads:read",
+        "admin:ads:write",
+        "admin:ads:delete",
+        "admin:carousel:read",
+        "admin:carousel:write",
+        "admin:carousel:delete",
+        "admin:deals:read",
+        "admin:deals:write",
+        "admin:featured:read",
+        "admin:featured:write",
+        "admin:sections:read",
+        "admin:sections:write",
+    ],
+    site_manager: [
+        "admin:dashboard:view",
+        "admin:site:read",
+        "admin:site:write",
+        "admin:navigation:read",
+        "admin:navigation:write",
+        "admin:sections:read",
+        "admin:sections:write",
+        "admin:carousel:read",
+        "admin:carousel:write",
+        "admin:faqs:read",
+        "admin:faqs:write",
+        "admin:media:read",
+        "admin:media:write",
+    ],
+    catalog_manager: [
+        "admin:dashboard:view",
+        "admin:categories:read",
+        "admin:categories:write",
+        "admin:categories:delete",
+        "admin:brands:read",
+        "admin:brands:write",
+        "admin:brands:delete",
+        "admin:products:read",
+        "admin:products:write",
+        "admin:media:read",
+        "admin:media:write",
+        "admin:deals:read",
+        "admin:deals:write",
+        "admin:featured:read",
+        "admin:featured:write",
+    ],
+    finance_manager: [
+        "admin:dashboard:view",
+        "admin:analytics:view",
+        "admin:payouts:read",
+        "admin:payouts:write",
+        "admin:orders:read",
+        "admin:returns:read",
+    ],
+    data_analyst: [
+        "admin:dashboard:view",
+        "admin:analytics:view",
+        "admin:orders:read",
+        "admin:payouts:read",
+        "admin:products:read",
+        "admin:users:read",
+        "admin:reviews:read",
+        "admin:carts:read",
+        "admin:wishlists:read",
+        "admin:bids:read",
+    ],
+    customer_support: [
+        "admin:dashboard:view",
+        "admin:support-tickets:read",
+        "admin:support-tickets:write",
+        "admin:support-tickets:assign",
+        "admin:support-tickets:close",
+        "admin:orders:read",
+        "admin:orders:write",
+        "admin:returns:read",
+        "admin:returns:write",
+        "admin:users:read",
+        "admin:contact:read",
+        "admin:notifications:read",
+        "admin:notifications:write",
+    ],
+    support_agent: [
+        "admin:dashboard:view",
+        "admin:support-tickets:read",
+        "admin:support-tickets:write",
+        "admin:support-tickets:assign",
+        "admin:support-tickets:close",
+        "admin:orders:read",
+        "admin:returns:read",
+        "admin:users:read",
+        "admin:contact:read",
+        "admin:notifications:read",
+        "admin:notifications:write",
+    ],
+    store_onboarding: [
+        "admin:dashboard:view",
+        "admin:stores:read",
+        "admin:stores:write",
+        "admin:store-addresses:read",
+        "admin:users:read",
+        "admin:notifications:write",
+    ],
+    trust_and_safety: [
+        "admin:dashboard:view",
+        "admin:users:read",
+        "admin:users:write",
+        "admin:user-bans:read",
+        "admin:user-bans:write",
+        "admin:orders:read",
+        "admin:products:read",
+        "admin:products:write",
+        "admin:reviews:read",
+        "admin:reviews:write",
+        "admin:reviews:delete",
+        "admin:bids:read",
+        "admin:bids:write",
+        "admin:sessions:read",
+        "admin:sessions:delete",
+        "admin:carts:read",
+        "admin:support-tickets:read",
+        "admin:support-tickets:write",
+        "admin:support-tickets:close",
+        "admin:scammers:read",
+        "admin:scammers:write",
+        "admin:scammers:verify",
+    ],
+    auction_monitor: [
+        "admin:dashboard:view",
+        "admin:bids:read",
+        "admin:bids:write",
+        "admin:products:read",
+        "admin:orders:read",
+        "admin:users:read",
+        "admin:notifications:write",
+    ],
+    scam_moderator: [
+        "admin:dashboard:view",
+        "admin:scammers:read",
+        "admin:scammers:write",
+        "admin:scammers:verify",
+        "admin:scammers:delete",
+        "admin:users:read",
+        "admin:media:read",
+        "admin:media:write",
+    ],
+};
+// ============================================================================
+// ROUTE → PERMISSION MAP
+// ============================================================================
+/**
+ * Maps each /admin/[section] pathname prefix to the permission required to READ it.
+ * Write/delete operations use the corresponding write/delete permission at the API level.
+ * Admin role bypasses this map entirely.
+ */
+export const ROUTE_PERMISSION_MAP = {
+    "/admin/dashboard": "admin:dashboard:view",
+    "/admin/users": "admin:users:read",
+    "/admin/products": "admin:products:read",
+    "/admin/orders": "admin:orders:read",
+    "/admin/return-requests": "admin:returns:read",
+    "/admin/stores": "admin:stores:read",
+    "/admin/store-addresses": "admin:store-addresses:read",
+    "/admin/analytics": "admin:analytics:view",
+    "/admin/payouts": "admin:payouts:read",
+    "/admin/categories": "admin:categories:read",
+    "/admin/brands": "admin:brands:read",
+    "/admin/coupons": "admin:coupons:read",
+    "/admin/deals": "admin:deals:read",
+    "/admin/featured": "admin:featured:read",
+    "/admin/reviews": "admin:reviews:read",
+    "/admin/blog": "admin:blog:read",
+    "/admin/bids": "admin:bids:read",
+    "/admin/media": "admin:media:read",
+    "/admin/site": "admin:site:read",
+    "/admin/navigation": "admin:navigation:read",
+    "/admin/sections": "admin:sections:read",
+    "/admin/carousel": "admin:carousel:read",
+    "/admin/ads": "admin:ads:read",
+    "/admin/faqs": "admin:faqs:read",
+    "/admin/newsletter": "admin:newsletter:read",
+    "/admin/contact": "admin:contact:read",
+    "/admin/events": "admin:events:read",
+    "/admin/event-entries": "admin:event-entries:read",
+    "/admin/support-tickets": "admin:support-tickets:read",
+    "/admin/scammers": "admin:scammers:read",
+    // System — rarely granted to employees
+    "/admin/sessions": "admin:sessions:read",
+    "/admin/notifications": "admin:notifications:read",
+    "/admin/carts": "admin:carts:read",
+    "/admin/wishlists": "admin:wishlists:read",
+    "/admin/feature-flags": "admin:feature-flags:read",
+    "/admin/copilot": "admin:copilot:view",
+    "/admin/team": "admin:team:read",
+};
+/** Default capabilities granted to every new store on creation. */
+export const DEFAULT_STORE_CAPABILITIES = [
+    "suggest_brands",
+    "create_coupons",
+];
+// ============================================================================
+// HELPERS
+// ============================================================================
+/**
+ * Check whether a permission array includes a required permission.
+ * Use server-side only — never trust client-supplied permission arrays.
+ */
+export function hasPermission(permissions, required) {
+    return permissions.includes(required);
+}
+/**
+ * Check whether a permission array includes ANY of the required permissions.
+ */
+export function hasAnyPermission(permissions, required) {
+    return required.some((p) => permissions.includes(p));
+}
+/**
+ * Check whether a permission array includes ALL of the required permissions.
+ */
+export function hasAllPermissions(permissions, required) {
+    return required.every((p) => permissions.includes(p));
+}
+/**
+ * Check whether a store's capabilities include a specific capability.
+ */
+export function hasCapability(capabilities, required) {
+    return capabilities.includes(required);
+}