@mohasinac/appkit 2.1.3 → 2.3.0

package/src/core/Logger.ts

@@ -1,209 +0,0 @@
-/**
- * Logger Class — @mohasinac/core
- *
- * Singleton class for application logging.
- * Pure utility — no framework or app-specific imports.
- *
- * The `logFileUrl` constructor option replaces the previous app-specific
- * `import("@/constants")` call, making this usable in any context.
- */
-
-export type LogLevel = "debug" | "info" | "warn" | "error";
-
-export interface LogEntry {
-  level: LogLevel;
-  message: string;
-  timestamp: Date;
-  data?: unknown;
-}
-
-export interface LoggerOptions {
-  minLevel?: LogLevel;
-  enableConsole?: boolean;
-  enableStorage?: boolean;
-  /**
-   * URL to POST error log entries. Set to your `/api/logs/write` route.
-   */
-  logFileUrl?: string;
-  /**
-   * @deprecated Prefer `logFileUrl`. When `true` and `logFileUrl` is not set,
-   * defaults to `/api/logs/write` for backward compatibility with the
-   * previous app-coupled Logger implementation.
-   */
-  enableFileLogging?: boolean;
-  maxEntries?: number;
-  /** Optional function to sanitize data before logging (e.g., PII redaction). */
-  sanitizer?: (data: unknown) => unknown;
-}
-
-export class Logger {
-  private static instance: Logger;
-  private logs: LogEntry[] = [];
-  private options: Required<
-    Omit<LoggerOptions, "logFileUrl" | "enableFileLogging" | "sanitizer">
-  > & {
-    logFileUrl?: string;
-    sanitizer?: (data: unknown) => unknown;
-  };
-  private levelPriority: Record<LogLevel, number> = {
-    debug: 0,
-    info: 1,
-    warn: 2,
-    error: 3,
-  };
-
-  private constructor(options?: LoggerOptions) {
-    // `enableFileLogging: true` is a backward-compat alias for logFileUrl.
-    const fileUrl =
-      options?.logFileUrl ??
-      (options?.enableFileLogging ? "/api/logs/write" : undefined);
-    this.options = {
-      minLevel: options?.minLevel ?? "debug",
-      enableConsole: options?.enableConsole ?? true,
-      enableStorage: options?.enableStorage ?? false,
-      logFileUrl: fileUrl,
-      maxEntries: options?.maxEntries ?? 1000,
-      sanitizer: options?.sanitizer,
-    };
-  }
-
-  /** Get singleton instance */
-  public static getInstance(options?: LoggerOptions): Logger {
-    if (!Logger.instance) {
-      Logger.instance = new Logger(options);
-    }
-    return Logger.instance;
-  }
-
-  /** Set or update the data sanitizer (e.g., for PII redaction). */
-  public static setSanitizer(fn: (data: unknown) => unknown): void {
-    Logger.getInstance().options.sanitizer = fn;
-  }
-
-  private shouldLog(level: LogLevel): boolean {
-    return (
-      this.levelPriority[level] >= this.levelPriority[this.options.minLevel]
-    );
-  }
-
-  private addLog(level: LogLevel, message: string, data?: unknown): void {
-    if (!this.shouldLog(level)) return;
-
-    const sanitized =
-      data && this.options.sanitizer ? this.options.sanitizer(data) : data;
-    const entry: LogEntry = {
-      level,
-      message,
-      timestamp: new Date(),
-      data: sanitized,
-    };
-
-    this.logs.push(entry);
-    if (this.logs.length > this.options.maxEntries) {
-      this.logs.shift();
-    }
-
-    if (this.options.enableConsole) {
-      this.logToConsole(entry);
-    }
-
-    if (this.options.enableStorage && typeof window !== "undefined") {
-      this.saveToStorage();
-    }
-
-    if (this.options.logFileUrl && level === "error") {
-      this.writeToFile(entry).catch(() => {
-        // Silently fail to prevent recursive logging
-      });
-    }
-  }
-
-  private logToConsole(entry: LogEntry): void {
-    const prefix = `[${entry.level.toUpperCase()}] ${entry.timestamp.toISOString()}`;
-    const message = `${prefix} ${entry.message}`;
-    switch (entry.level) {
-      case "debug":
-        console.debug(message, entry.data);
-        break;
-      case "info":
-        console.info(message, entry.data);
-        break;
-      case "warn":
-        console.warn(message, entry.data);
-        break;
-      case "error":
-        console.error(message, entry.data);
-        break;
-    }
-  }
-
-  private saveToStorage(): void {
-    try {
-      localStorage.setItem("app_logs", JSON.stringify(this.logs));
-    } catch {
-      // Silently fail
-    }
-  }
-
-  private async writeToFile(entry: LogEntry): Promise<void> {
-    if (typeof window === "undefined" || !this.options.logFileUrl) return;
-    try {
-      await fetch(this.options.logFileUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          level: entry.level,
-          message: entry.message,
-          timestamp: entry.timestamp.toISOString(),
-          data: entry.data,
-        }),
-      });
-    } catch {
-      // Silently fail
-    }
-  }
-
-  public debug(message: string, data?: unknown): void {
-    this.addLog("debug", message, data);
-  }
-
-  public info(message: string, data?: unknown): void {
-    this.addLog("info", message, data);
-  }
-
-  public warn(message: string, data?: unknown): void {
-    this.addLog("warn", message, data);
-  }
-
-  public error(message: string, data?: unknown): void {
-    this.addLog("error", message, data);
-  }
-
-  public getLogs(level?: LogLevel): LogEntry[] {
-    if (level) return this.logs.filter((log) => log.level === level);
-    return [...this.logs];
-  }
-
-  public clear(): void {
-    this.logs = [];
-    if (this.options.enableStorage && typeof window !== "undefined") {
-      localStorage.removeItem("app_logs");
-    }
-  }
-
-  public export(): string {
-    return JSON.stringify(this.logs, null, 2);
-  }
-
-  public getStats(): Record<LogLevel, number> {
-    return {
-      debug: this.logs.filter((l) => l.level === "debug").length,
-      info: this.logs.filter((l) => l.level === "info").length,
-      warn: this.logs.filter((l) => l.level === "warn").length,
-      error: this.logs.filter((l) => l.level === "error").length,
-    };
-  }
-}
-
-/** Shared singleton instance */
-export const logger = Logger.getInstance();

package/src/core/Queue.ts

@@ -1,126 +0,0 @@
-/**
- * Queue Class — @mohasinac/core
- *
- * Generic priority queue for task management.
- * Pure utility — no framework or app-specific imports.
- */
-
-import { Logger } from "./Logger";
-
-const qLogger = Logger.getInstance();
-
-export interface QueueOptions {
-  concurrency?: number;
-  autoStart?: boolean;
-}
-
-export interface Task<T = unknown> {
-  id: string;
-  fn: () => Promise<T>;
-  priority?: number;
-}
-
-export class Queue<T = unknown> {
-  private tasks: Task<T>[] = [];
-  private running: number = 0;
-  private readonly concurrency: number;
-  private autoStart: boolean;
-  private results: Map<string, T> = new Map();
-  private errors: Map<string, Error> = new Map();
-
-  constructor(options?: QueueOptions) {
-    this.concurrency = options?.concurrency ?? 1;
-    this.autoStart = options?.autoStart ?? true;
-  }
-
-  /** Add a task to the queue */
-  public add(id: string, fn: () => Promise<T>, priority: number = 0): void {
-    this.tasks.push({ id, fn, priority });
-    this.tasks.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
-    if (this.autoStart) {
-      this.process();
-    }
-  }
-
-  private process(): void {
-    while (this.running < this.concurrency && this.tasks.length > 0) {
-      const task = this.tasks.shift();
-      if (!task) break;
-      this.running++;
-      task
-        .fn()
-        .then((result) => {
-          this.results.set(task.id, result);
-        })
-        .catch((error: unknown) => {
-          this.errors.set(task.id, error as Error);
-        })
-        .finally(() => {
-          this.running--;
-          this.process();
-        })
-        .catch((err: unknown) => {
-          qLogger.error("Queue.process error in finally", { err });
-        });
-    }
-  }
-
-  public start(): void {
-    this.process();
-  }
-
-  public pause(): void {
-    this.autoStart = false;
-  }
-
-  public resume(): void {
-    this.autoStart = true;
-    this.process();
-  }
-
-  public clear(): void {
-    this.tasks = [];
-    this.results.clear();
-    this.errors.clear();
-  }
-
-  public getResult(id: string): T | undefined {
-    return this.results.get(id);
-  }
-
-  public getError(id: string): Error | undefined {
-    return this.errors.get(id);
-  }
-
-  public size(): number {
-    return this.tasks.length;
-  }
-
-  public getRunning(): number {
-    return this.running;
-  }
-
-  public isEmpty(): boolean {
-    return this.tasks.length === 0 && this.running === 0;
-  }
-
-  public async waitForCompletion(): Promise<void> {
-    while (!this.isEmpty()) {
-      await new Promise<void>((resolve) => setTimeout(resolve, 100));
-    }
-  }
-
-  public getStats(): {
-    pending: number;
-    running: number;
-    completed: number;
-    failed: number;
-  } {
-    return {
-      pending: this.tasks.length,
-      running: this.running,
-      completed: this.results.size,
-      failed: this.errors.size,
-    };
-  }
-}

package/src/core/StorageManager.ts

@@ -1,167 +0,0 @@
-/**
- * StorageManager Class — @mohasinac/core
- *
- * Singleton class for managing localStorage and sessionStorage with
- * namespace prefixing and SSR-safe fallbacks.
- * Pure utility — no framework or app-specific imports.
- */
-
-import { Logger } from "./Logger";
-
-const sLogger = Logger.getInstance();
-
-export type StorageType = "local" | "session";
-
-export interface StorageOptions {
-  type?: StorageType;
-  prefix?: string;
-}
-
-export class StorageManager {
-  /** Per-prefix instance map — prevents namespace collisions */
-  private static instances = new Map<string, StorageManager>();
-  private readonly prefix: string;
-
-  private constructor(prefix: string = "app_") {
-    this.prefix = prefix;
-  }
-
-  /**
-   * Get-or-create a StorageManager for the given prefix.
-   * Each prefix returns an independent instance.
-   */
-  public static getInstance(prefix: string = ""): StorageManager {
-    if (!StorageManager.instances.has(prefix)) {
-      StorageManager.instances.set(prefix, new StorageManager(prefix));
-    }
-    return StorageManager.instances.get(prefix)!;
-  }
-
-  private getStorage(type: StorageType): Storage | null {
-    try {
-      if (typeof window === "undefined") return null;
-      const storage =
-        type === "local" ? window.localStorage : window.sessionStorage;
-      return storage ?? null;
-    } catch {
-      return null;
-    }
-  }
-
-  private generateKey(key: string): string {
-    return `${this.prefix}${key}`;
-  }
-
-  public set<T>(key: string, value: T, options?: StorageOptions): boolean {
-    const storage = this.getStorage(options?.type ?? "local");
-    if (!storage) return false;
-    try {
-      storage.setItem(this.generateKey(key), JSON.stringify(value));
-      return true;
-    } catch (error) {
-      sLogger.error("StorageManager.set error", { error });
-      return false;
-    }
-  }
-
-  public get<T>(key: string, options?: StorageOptions): T | null {
-    const storage = this.getStorage(options?.type ?? "local");
-    if (!storage) return null;
-    try {
-      const item = storage.getItem(this.generateKey(key));
-      if (item === null) return null;
-      return JSON.parse(item) as T;
-    } catch (error) {
-      sLogger.error("StorageManager.get error", { error });
-      return null;
-    }
-  }
-
-  public remove(key: string, options?: StorageOptions): boolean {
-    const storage = this.getStorage(options?.type ?? "local");
-    if (!storage) return false;
-    try {
-      storage.removeItem(this.generateKey(key));
-      return true;
-    } catch (error) {
-      sLogger.error("StorageManager.remove error", { error });
-      return false;
-    }
-  }
-
-  public clear(options?: StorageOptions): boolean {
-    const storage = this.getStorage(options?.type ?? "local");
-    if (!storage) return false;
-    try {
-      const keys = Object.keys(storage);
-      keys.forEach((k) => {
-        if (k.startsWith(this.prefix)) storage.removeItem(k);
-      });
-      return true;
-    } catch (error) {
-      sLogger.error("StorageManager.clear error", { error });
-      return false;
-    }
-  }
-
-  public has(key: string, options?: StorageOptions): boolean {
-    return this.get(key, options) !== null;
-  }
-
-  public keys(options?: StorageOptions): string[] {
-    const storage = this.getStorage(options?.type ?? "local");
-    if (!storage) return [];
-    const result: string[] = [];
-    for (let i = 0; i < storage.length; i++) {
-      const k = storage.key(i);
-      if (k?.startsWith(this.prefix)) {
-        result.push(k.slice(this.prefix.length));
-      }
-    }
-    return result;
-  }
-
-  public size(options?: StorageOptions): number {
-    const storage = this.getStorage(options?.type ?? "local");
-    if (!storage) return 0;
-    let bytes = 0;
-    for (let i = 0; i < storage.length; i++) {
-      const k = storage.key(i);
-      if (k?.startsWith(this.prefix)) {
-        const v = storage.getItem(k);
-        bytes += k.length + (v?.length ?? 0);
-      }
-    }
-    return bytes;
-  }
-
-  public isAvailable(type: StorageType = "local"): boolean {
-    const storage = this.getStorage(type);
-    if (!storage) return false;
-    try {
-      const testKey = "__storage_test__";
-      storage.setItem(testKey, "1");
-      storage.removeItem(testKey);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  public getAll<T = unknown>(options?: StorageOptions): Record<string, T> {
-    const storage = this.getStorage(options?.type ?? "local");
-    if (!storage) return {};
-    const result: Record<string, T> = {};
-    for (let i = 0; i < storage.length; i++) {
-      const k = storage.key(i);
-      if (k?.startsWith(this.prefix)) {
-        const v = this.get<T>(k.slice(this.prefix.length), options);
-        if (v !== null) result[k.slice(this.prefix.length)] = v;
-      }
-    }
-    return result;
-  }
-}
-
-/** Default StorageManager instance (empty prefix) */
-export const storageManager = StorageManager.getInstance("");

package/src/core/copilot-log.repository.ts

@@ -1,106 +0,0 @@
-import { getProviders } from "../contracts";
-import type { IRepository } from "../contracts";
-
-export type CopilotFeedback = "positive" | "negative";
-
-export interface CopilotLogDocument {
-  id: string;
-  userId: string;
-  userName: string;
-  conversationId: string;
-  prompt: string;
-  response: string;
-  model: string;
-  promptTokens?: number;
-  responseTokens?: number;
-  durationMs?: number;
-  feedback: CopilotFeedback | null;
-  createdAt: Date;
-  updatedAt?: Date;
-}
-
-export interface CopilotLogCreateInput {
-  userId: string;
-  userName: string;
-  conversationId: string;
-  prompt: string;
-  response: string;
-  model: string;
-  promptTokens?: number;
-  responseTokens?: number;
-  durationMs?: number;
-}
-
-function resolveRepository(): IRepository<CopilotLogDocument> {
-  const provider = getProviders().db;
-  if (!provider) {
-    throw new Error(
-      "DB provider is not registered. Configure providers before using CopilotLogRepository.",
-    );
-  }
-  return provider.getRepository<CopilotLogDocument>("copilotLogs");
-}
-
-export class CopilotLogRepository {
-  private _repo: IRepository<CopilotLogDocument> | null;
-  private readonly _collection: string | null;
-
-  constructor(
-    repoOrCollection: IRepository<CopilotLogDocument> | string | null = null,
-  ) {
-    if (typeof repoOrCollection === "string") {
-      this._repo = null;
-      this._collection = repoOrCollection;
-    } else {
-      this._repo = repoOrCollection;
-      this._collection = null;
-    }
-  }
-
-  private get repo(): IRepository<CopilotLogDocument> {
-    if (!this._repo) {
-      if (this._collection) {
-        const provider = getProviders().db;
-        if (!provider) {
-          throw new Error(
-            "DB provider is not registered. Configure providers before using CopilotLogRepository.",
-          );
-        }
-        this._repo = provider.getRepository<CopilotLogDocument>(
-          this._collection,
-        );
-      } else {
-        this._repo = resolveRepository();
-      }
-    }
-    return this._repo;
-  }
-
-  async create(input: CopilotLogCreateInput): Promise<CopilotLogDocument> {
-    return this.repo.create({
-      ...input,
-      feedback: null,
-    } as Omit<CopilotLogDocument, "id" | "createdAt" | "updatedAt">);
-  }
-
-  async findByConversation(
-    conversationId: string,
-    limit = 50,
-  ): Promise<CopilotLogDocument[]> {
-    const result = await this.repo.findAll({
-      filters: `conversationId==${conversationId}`,
-      sort: "createdAt",
-      order: "asc",
-      page: 1,
-      perPage: limit,
-    });
-
-    return result.data;
-  }
-
-  async setFeedback(logId: string, feedback: CopilotFeedback): Promise<void> {
-    await this.repo.update(logId, { feedback });
-  }
-}
-
-export const copilotLogRepository = new CopilotLogRepository();

package/src/core/index.ts

@@ -1,39 +0,0 @@
-/**
- * @mohasinac/core — Stage B2
- *
- * Pure utility classes extracted from src/classes/.
- * No framework dependencies, no app-specific imports.
- */
-
-export { Logger, logger } from "./Logger";
-export type { LogLevel, LogEntry, LoggerOptions } from "./Logger";
-
-export { Queue } from "./Queue";
-export type { QueueOptions, Task } from "./Queue";
-
-export { StorageManager, storageManager } from "./StorageManager";
-export type { StorageType, StorageOptions } from "./StorageManager";
-
-export { EventBus, eventBus } from "./EventBus";
-export type { EventSubscription } from "./EventBus";
-
-export { CacheManager, cacheManager } from "./CacheManager";
-export type { CacheOptions, CacheEntry } from "./CacheManager";
-
-export {
-  SITE_CONFIG,
-  FEATURE_FLAGS,
-  createSiteConfig,
-  resolveSiteConfig,
-} from "./site-config";
-export type { RuntimeSiteConfig } from "./site-config";
-
-export {
-  CopilotLogRepository,
-  copilotLogRepository,
-} from "./copilot-log.repository";
-export type {
-  CopilotFeedback,
-  CopilotLogDocument,
-  CopilotLogCreateInput,
-} from "./copilot-log.repository";