@mohasinac/appkit 2.1.3 → 2.3.0

package/src/features/loyalty/api/history/route.ts

@@ -1,74 +0,0 @@
-/**
- * feat-loyalty — GET /api/loyalty/history
- *
- * User loyalty transaction history.
- *
- * Consumer stub:
- * ```ts
- * export { loyaltyHistoryGET as GET } from "@mohasinac/feat-loyalty";
- * ```
- */
-
-import { NextResponse } from "next/server.js";
-import { getProviders } from "../../../../contracts";
-
-function numParam(url: URL, key: string, fallback: number): number {
-  const v = url.searchParams.get(key);
-  const n = v !== null ? Number(v) : NaN;
-  return Number.isFinite(n) ? n : fallback;
-}
-
-export async function GET(request: Request): Promise<NextResponse> {
-  try {
-    const url = new URL(request.url);
-    const userId = url.searchParams.get("userId");
-    const page = Math.max(1, numParam(url, "page", 1));
-    const pageSize = Math.min(100, Math.max(1, numParam(url, "pageSize", 20)));
-
-    if (!userId) {
-      return NextResponse.json(
-        { success: false, error: "User ID required" },
-        { status: 400 },
-      );
-    }
-
-    const { db } = getProviders();
-    if (!db)
-      return NextResponse.json(
-        { success: false, error: "DB not configured" },
-        { status: 503 },
-      );
-
-    const repo = db.getRepository<Record<string, unknown>>(
-      "loyalty_transactions",
-    );
-    const result = await repo.findAll({
-      filters: `userId==${userId}`,
-      sort: "-createdAt",
-      page,
-      perPage: pageSize,
-    });
-
-    const totalPages = Math.max(1, Math.ceil(result.total / pageSize));
-
-    return NextResponse.json({
-      success: true,
-      data: {
-        items: result.data,
-        total: result.total,
-        page,
-        pageSize,
-        totalPages,
-        hasMore: page < totalPages,
-      },
-    });
-  } catch (error) {
-    return NextResponse.json(
-      {
-        success: false,
-        error: error instanceof Error ? error.message : "Internal server error",
-      },
-      { status: 500 },
-    );
-  }
-}

package/src/features/loyalty/api/redeem/route.ts

@@ -1,51 +0,0 @@
-/**
- * feat-loyalty — POST /api/loyalty/redeem
- *
- * Redeem loyalty points for rewards.
- *
- * Consumer stub:
- * ```ts
- * export { loyaltyRedeemPOST as POST } from "@mohasinac/feat-loyalty";
- * ```
- */
-
-import { NextResponse } from "next/server.js";
-import { getProviders } from "../../../../contracts";
-
-export async function POST(request: Request): Promise<NextResponse> {
-  try {
-    const body = await request.json();
-
-    const { db } = getProviders();
-    if (!db)
-      return NextResponse.json(
-        { success: false, error: "DB not configured" },
-        { status: 503 },
-      );
-
-    const repo = db.getRepository<Record<string, unknown>>(
-      "loyalty_transactions",
-    );
-    const created = await repo.create({
-      ...body,
-      type: "redeem",
-      createdAt: new Date(),
-    });
-
-    return NextResponse.json(
-      {
-        success: true,
-        data: created,
-      },
-      { status: 201 },
-    );
-  } catch (error) {
-    return NextResponse.json(
-      {
-        success: false,
-        error: error instanceof Error ? error.message : "Internal server error",
-      },
-      { status: 500 },
-    );
-  }
-}

package/src/features/loyalty/columns/index.ts

@@ -1,61 +0,0 @@
-import type { TableColumn, ColumnExtensionOpts } from "../../../contracts";
-import type { LoyaltyBalance } from "../types";
-
-/**
- * Default admin columns for loyalty balance records.
- * Use `buildLoyaltyColumns()` to customise via overrides / extras / omit.
- */
-export const loyaltyAdminColumns: TableColumn<LoyaltyBalance>[] = [
-  {
-    key: "uid",
-    header: "User ID",
-    sortable: false,
-  },
-  {
-    key: "hcCoins",
-    header: "Coins",
-    sortable: true,
-  },
-  {
-    key: "coinHistory",
-    header: "Last Transaction",
-    sortable: false,
-    render: (item) => {
-      if (!item.coinHistory?.length) return "—";
-      const last = item.coinHistory[item.coinHistory.length - 1];
-      return last?.timestamp ?? "—";
-    },
-  },
-];
-
-/**
- * Factory that returns columns for the loyalty admin table.
- *
- * @example
- * const cols = buildLoyaltyColumns<MyLoyaltyBalance>({
- *   extras: [{ key: "tier", header: "Tier", render: (l) => l.tier }],
- *   omit: ["coinHistory"],
- * });
- */
-export function buildLoyaltyColumns<T extends LoyaltyBalance = LoyaltyBalance>(
-  opts?: ColumnExtensionOpts<T>
-): TableColumn<T>[] {
-  let base = loyaltyAdminColumns as unknown as TableColumn<T>[];
-
-  if (opts?.omit?.length) {
-    base = base.filter((c) => !opts.omit!.includes(c.key as string));
-  }
-
-  if (opts?.overrides) {
-    base = base.map((c) => {
-      const override = (opts.overrides as Record<string, Partial<TableColumn<T>>>)[c.key as string];
-      return override ? { ...c, ...override } : c;
-    });
-  }
-
-  if (opts?.extras?.length) {
-    base = [...base, ...opts.extras];
-  }
-
-  return base;
-}

package/src/features/loyalty/components/CoinsDisplay.tsx

@@ -1,36 +0,0 @@
-"use client";
-
-import React from "react";
-import { Div, Span, Text } from "../../../ui";
-
-interface CoinsBadgeProps {
-  coins: number;
-  className?: string;
-}
-
-export function CoinsBadge({ coins, className }: CoinsBadgeProps) {
-  return (
-    <Span
-      className={`inline-flex items-center gap-1 rounded-full bg-amber-100 px-2 py-0.5 text-xs font-semibold text-amber-800 ${className ?? ""}`}
-    >
-      <Span aria-hidden="true">🪙</Span>
-      {coins.toLocaleString()}
-    </Span>
-  );
-}
-
-interface CoinsDisplayProps {
-  coins: number;
-  label?: string;
-}
-
-export function CoinsDisplay({ coins, label = "HC Coins" }: CoinsDisplayProps) {
-  return (
-    <Div className="flex flex-col items-center gap-1">
-      <Text className="text-3xl font-bold text-amber-600">
-        {coins.toLocaleString()}
-      </Text>
-      <Text className="text-sm text-gray-500">{label}</Text>
-    </Div>
-  );
-}

package/src/features/loyalty/components/index.ts

@@ -1 +0,0 @@
-export { CoinsBadge, CoinsDisplay } from "./CoinsDisplay";

package/src/features/loyalty/hooks/useLoyaltyBalance.ts

@@ -1,17 +0,0 @@
-"use client";
-
-import { useQuery } from "@tanstack/react-query";
-import type { LoyaltyBalance } from "../types";
-
-export function useLoyaltyBalance(uid: string | undefined) {
-  return useQuery<LoyaltyBalance | null>({
-    queryKey: ["loyalty", "balance", uid],
-    queryFn: async () => {
-      if (!uid) return null;
-      const res = await fetch(`/api/loyalty/balance?uid=${uid}`);
-      if (!res.ok) return null;
-      return res.json() as Promise<LoyaltyBalance>;
-    },
-    enabled: !!uid,
-  });
-}

package/src/features/loyalty/index.ts

@@ -1,7 +0,0 @@
-export * from "./types";
-export * from "./schemas";
-export * from "./columns";
-export * from "./hooks/useLoyaltyBalance";
-export * from "./components";
-export { LoyaltyRepository } from "./repository/loyalty.repository";
-export { manifest } from "./manifest";

package/src/features/loyalty/manifest.ts

@@ -1,18 +0,0 @@
-import type { FeatureManifest } from "../../contracts";
-
-export const manifest: FeatureManifest = {
-  name: "loyalty",
-  i18nNamespace: "loyalty",
-  envKeys: [],
-  routes: [
-    { segment: "[locale]/account/coins", exports: { default: "LoyaltyPageView" } },
-    { segment: "[locale]/admin/loyalty", exports: { default: "AdminLoyaltyView" }, adminOnly: true },
-  ],
-  apiRoutes: [
-    { segment: "api/loyalty/balance", methods: ["GET"] },
-    { segment: "api/loyalty/earn", methods: ["POST"] },
-    { segment: "api/loyalty/redeem", methods: ["POST"] },
-    { segment: "api/loyalty/history", methods: ["GET"] },
-    { segment: "api/admin/loyalty/grant", methods: ["POST"] },
-  ],
-};

package/src/features/loyalty/messages/en.json

@@ -1,19 +0,0 @@
-{
-    "loyalty": {
-        "title": "HC Coins",
-        "balance": "Your Coin Balance",
-        "earn": "Earn Coins",
-        "redeem": "Redeem Coins",
-        "history": "Coin History",
-        "noHistory": "No coin transactions yet.",
-        "earnedFor": "Earned for order",
-        "redeemedFor": "Redeemed on order",
-        "adminGrant": "Admin grant",
-        "refund": "Refund",
-        "coinsEarned": "{coins} coins earned",
-        "coinsRedeemed": "{coins} coins redeemed",
-        "worthRupees": "Worth ₹{amount}",
-        "minRequired": "Minimum {min} coins required to redeem",
-        "notActive": "Loyalty program is currently inactive"
-    }
-}

package/src/features/loyalty/repository/loyalty.repository.ts

@@ -1,29 +0,0 @@
-import type { IRepository } from "../../../contracts";
-import type { LoyaltyBalance, CoinHistoryEntry } from "../types";
-
-export class LoyaltyRepository {
-  constructor(private readonly repo: IRepository<LoyaltyBalance>) {}
-
-  async getBalance(uid: string): Promise<LoyaltyBalance | null> {
-    return this.repo.findById(uid);
-  }
-
-  async addCoins(
-    uid: string,
-    delta: number,
-    entry: Omit<CoinHistoryEntry, "timestamp">,
-  ): Promise<void> {
-    const user = await this.repo.findById(uid);
-    if (!user) return;
-
-    const current = user.hcCoins ?? 0;
-    const history = user.coinHistory ?? [];
-    await this.repo.update(uid, {
-      hcCoins: current + delta,
-      coinHistory: [
-        ...history,
-        { ...entry, delta, timestamp: new Date().toISOString() },
-      ],
-    });
-  }
-}

package/src/features/loyalty/schemas/index.ts

@@ -1,44 +0,0 @@
-import { z } from "zod";
-
-/**
- * Reason categories for loyalty coin transactions.
- */
-export const coinReasonSchema = z.enum([
-  "order_reward",
-  "referral",
-  "review_reward",
-  "manual_credit",
-  "manual_debit",
-  "redemption",
-  "expiry",
-]);
-
-export const coinHistoryEntrySchema = z.object({
-  delta: z.number(),
-  reason: coinReasonSchema,
-  orderId: z.string().optional(),
-  timestamp: z.string().optional(),
-});
-
-/**
- * Base Zod schema for a loyalty balance record.
- *
- * @example
- * import { loyaltyBalanceSchema } from "@mohasinac/feat-loyalty";
- *
- * const mySchema = loyaltyBalanceSchema.extend({
- *   tier: z.enum(["bronze", "silver", "gold"]),
- * });
- */
-export const loyaltyBalanceSchema = z.object({
-  uid: z.string(),
-  hcCoins: z.number().default(0),
-  coinHistory: z.array(coinHistoryEntrySchema).optional(),
-});
-
-export const loyaltyConfigSchema = z.object({
-  coinsPerOrderUnit: z.number(),
-  minRedeemableCoins: z.number(),
-  maxRedemptionPercentPerOrder: z.number(),
-  coinExpiryDays: z.number().optional(),
-});

package/src/features/loyalty/types/index.ts

@@ -1,43 +0,0 @@
-export interface LoyaltyConfig {
-  coinsPerRupee: number;
-  rupeePerCoin: number;
-  minCoinsToRedeem: number;
-  maxRedeemPercent: number;
-  active: boolean;
-}
-
-export type CoinReason = "purchase" | "redemption" | "admin-grant" | "refund";
-
-export interface CoinHistoryEntry {
-  delta: number;
-  reason: CoinReason;
-  orderId?: string;
-  timestamp: string;
-}
-
-export interface LoyaltyBalance {
-  uid: string;
-  hcCoins: number;
-  coinHistory: CoinHistoryEntry[];
-}
-
-export interface EarnCoinsInput {
-  uid: string;
-  orderTotal: number;
-  orderId: string;
-  config: LoyaltyConfig;
-}
-
-export interface RedeemCoinsInput {
-  uid: string;
-  coinsToRedeem: number;
-  orderId: string;
-  config: LoyaltyConfig;
-}
-
-export interface RedeemCoinsResult {
-  coinsRedeemed: number;
-  discountAmount: number;
-}
-
-export { calculateCoinsEarned, calculateMaxRedeemable, coinsToRupees, applyCoinsToOrder } from "./loyalty-math";

package/src/features/loyalty/types/loyalty-math.ts

@@ -1,36 +0,0 @@
-import type { LoyaltyConfig } from "./index";
-
-export function calculateCoinsEarned(orderTotal: number, config: LoyaltyConfig): number {
-  if (!config.active || orderTotal <= 0) return 0;
-  return Math.floor(orderTotal * config.coinsPerRupee);
-}
-
-export function calculateMaxRedeemable(
-  userCoins: number,
-  orderTotal: number,
-  config: LoyaltyConfig,
-): number {
-  if (!config.active || userCoins < config.minCoinsToRedeem || orderTotal <= 0) return 0;
-  const maxDiscountRupees = Math.floor((orderTotal * config.maxRedeemPercent) / 100);
-  const maxCoinsByPercent = Math.floor(maxDiscountRupees / config.rupeePerCoin);
-  return Math.min(userCoins, maxCoinsByPercent);
-}
-
-export function coinsToRupees(coins: number, config: LoyaltyConfig): number {
-  if (coins <= 0) return 0;
-  return Math.floor(coins * config.rupeePerCoin);
-}
-
-/**
- * Calculate the INR discount for a given coin redemption.
- * Ensures the discount never exceeds the order total.
- */
-export function applyCoinsToOrder(
-  coinsToRedeem: number,
-  orderTotal: number,
-  config: LoyaltyConfig,
-): number {
-  if (!config.active || coinsToRedeem <= 0 || orderTotal <= 0) return 0;
-  const discount = coinsToRupees(coinsToRedeem, config);
-  return Math.min(discount, orderTotal);
-}

package/src/features/media/MediaAvatar.tsx

@@ -1,37 +0,0 @@
-import { MediaImage } from "./MediaImage";
-import { Div } from "../../ui";
-
-export interface MediaAvatarProps {
-  /** Avatar image URL. Shows a 👤 fallback when undefined. */
-  src: string | undefined;
-  /** Descriptive alt text — required for accessibility. */
-  alt: string;
-  /** Circular size preset. Defaults to `'md'`. */
-  size?: "sm" | "md" | "lg" | "xl";
-  /** Additional classes applied to the outer circle wrapper. */
-  className?: string;
-}
-
-const sizeClasses: Record<NonNullable<MediaAvatarProps["size"]>, string> = {
-  sm: "w-8 h-8",
-  md: "w-10 h-10",
-  lg: "w-14 h-14",
-  xl: "w-20 h-20",
-};
-
-export function MediaAvatar({
-  src,
-  alt,
-  size = "md",
-  className = "",
-}: MediaAvatarProps) {
-  return (
-    <Div
-      className={`relative ${sizeClasses[size]} rounded-full overflow-hidden flex-shrink-0 ${className}`}
-    >
-      <MediaImage src={src} alt={alt} size="avatar" />
-    </Div>
-  );
-}
-
-export default MediaAvatar;

package/src/features/media/MediaImage.tsx

@@ -1,119 +0,0 @@
-"use client";
-
-import Image from "next/image";
-import { useState } from "react";
-import { Div, Span } from "../../ui";
-
-// ─── Size presets ─────────────────────────────────────────────────────────────
-
-export type MediaImageSize =
-  | "thumbnail"
-  | "card"
-  | "hero"
-  | "banner"
-  | "gallery"
-  | "avatar";
-
-const SIZE_HINTS: Record<MediaImageSize, string> = {
-  thumbnail: "(max-width: 640px) 80px, (max-width: 1024px) 96px, 112px",
-  card: "(max-width: 640px) 50vw, (max-width: 1024px) 33vw, 25vw",
-  hero: "100vw",
-  banner: "100vw",
-  gallery: "(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw",
-  avatar: "(max-width: 640px) 48px, 56px",
-};
-
-const FALLBACK_ICONS: Record<MediaImageSize, string> = {
-  thumbnail: "📦",
-  card: "📦",
-  hero: "🖼️",
-  banner: "🖼️",
-  gallery: "📦",
-  avatar: "👤",
-};
-
-// ─── MediaImageProps ──────────────────────────────────────────────────────────
-
-export interface MediaImageProps {
-  /** Image URL. When undefined the fallback icon is rendered instead. */
-  src: string | undefined;
-  /** Descriptive alt text — required for accessibility and SEO. */
-  alt: string;
-  /**
-   * Sizing preset — controls the `sizes` attribute passed to Next.js Image.
-   * Defaults to `'card'`.
-   */
-  size?: MediaImageSize;
-  /** Pass `true` for above-the-fold hero / banner images to skip lazy loading. */
-  priority?: boolean;
-  /** CSS object-fit applied to the underlying img element. Defaults to `'cover'`. */
-  objectFit?: "cover" | "contain";
-  /**
-   * Emoji or text to show when `src` is undefined.
-   * Falls back to the per-size default icon.
-   */
-  fallback?: string;
-  /**
-   * Extra Tailwind classes applied to the absolute-fill wrapper div.
-   * Use for hover animations, e.g. `group-hover:scale-110 transition-transform duration-300`.
-   */
-  className?: string;
-}
-
-export function MediaImage({
-  src,
-  alt,
-  size = "card",
-  priority = false,
-  objectFit = "cover",
-  fallback,
-  className,
-}: MediaImageProps) {
-  const [hasError, setHasError] = useState(false);
-  const [isLoaded, setIsLoaded] = useState(false);
-  const icon = fallback ?? FALLBACK_ICONS[size];
-  const fitClass = objectFit === "contain" ? "object-contain" : "object-cover";
-
-  if (!src || hasError) {
-    return (
-      <Div
-        className={`absolute inset-0 flex items-center justify-center bg-zinc-100 dark:bg-slate-800 text-zinc-400 text-4xl${className ? ` ${className}` : ""}`}
-        role="img"
-        aria-label={alt}
-      >
-        <Span aria-hidden="true">{icon}</Span>
-      </Div>
-    );
-  }
-
-  const isSvg =
-    src.toLowerCase().endsWith(".svg") ||
-    src.includes("image/svg") ||
-    /[./]svg(\?|$)/i.test(src);
-
-  return (
-    <Div
-      className={`absolute inset-0 overflow-hidden${className ? ` ${className}` : ""}`}
-    >
-      {!isLoaded && (
-        <Div
-          className="absolute inset-0 bg-zinc-200 dark:bg-slate-700 animate-pulse"
-          aria-hidden="true"
-        />
-      )}
-      <Image
-        src={src}
-        alt={alt}
-        fill
-        priority={priority}
-        className={fitClass}
-        sizes={SIZE_HINTS[size]}
-        onLoad={() => setIsLoaded(true)}
-        onError={() => setHasError(true)}
-        unoptimized={isSvg}
-      />
-    </Div>
-  );
-}
-
-export default MediaImage;