@mohasinac/appkit 2.1.3 → 2.3.0

package/src/next/api/api-response.ts

@@ -1,72 +0,0 @@
-/**
- * Standardized API Response Utilities
- *
- * Provides consistent response formatting across all Next.js API routes.
- * No app-specific dependencies — safe to use in any project.
- */
-
-import { NextResponse } from "next/server";
-
-export interface ApiSuccessResponse<T = unknown> {
-  success: true;
-  data?: T;
-  message?: string;
-  meta?: Record<string, unknown>;
-}
-
-export interface ApiErrorResponse {
-  success: false;
-  error: string;
-  details?: unknown;
-}
-
-export function successResponse<T>(
-  data?: T,
-  message?: string,
-  status: number = 200,
-  meta?: Record<string, unknown>,
-): NextResponse<ApiSuccessResponse<T>> {
-  return NextResponse.json(
-    {
-      success: true,
-      ...(data !== undefined && { data }),
-      ...(message && { message }),
-      ...(meta && { meta }),
-    },
-    { status },
-  );
-}
-
-export function errorResponse(
-  error: string,
-  status: number = 400,
-  details?: unknown,
-): NextResponse<ApiErrorResponse> {
-  return NextResponse.json(
-    {
-      success: false,
-      error,
-      ...(details !== undefined && { details }),
-    },
-    { status },
-  );
-}
-
-/** Pre-built shorthand factories for common HTTP error responses. */
-export const ApiErrors = {
-  unauthorized: (message = "Unauthorized") => errorResponse(message, 401),
-
-  forbidden: (message = "Forbidden") => errorResponse(message, 403),
-
-  notFound: (resource = "Resource") =>
-    errorResponse(`${resource} not found`, 404),
-
-  badRequest: (message = "Bad request", details?: unknown) =>
-    errorResponse(message, 400, details),
-
-  internalError: (message = "Internal server error") =>
-    errorResponse(message, 500),
-
-  validationError: (details: unknown) =>
-    errorResponse("Validation failed", 422, details),
-};

package/src/next/api/apiHandler.ts

@@ -1,178 +0,0 @@
-interface SafeParseSchema<TInput> {
-  safeParse: (input: unknown) =>
-    | { success: true; data: TInput }
-    | { success: false; error: { issues?: unknown[] } };
-}
-
-export interface ApiRateLimitResult {
-  success: boolean;
-  limit: number;
-  remaining: number;
-  reset: number;
-}
-
-export interface ApiHandlerOptions<
-  TInput,
-  TParams extends Record<string, string>,
-  TRole,
-  TRateLimitConfig,
-  TUser,
-> {
-  auth?: boolean;
-  roles?: TRole[];
-  rateLimit?: TRateLimitConfig;
-  schema?: SafeParseSchema<TInput>;
-  handler: (ctx: {
-    request: Request;
-    user?: TUser;
-    body?: TInput;
-    params?: TParams;
-  }) => Promise<Response>;
-}
-
-export interface ApiHandlerFactoryDeps<TRole, TRateLimitConfig, TUser> {
-  applyRateLimit: (
-    request: Request,
-    config: TRateLimitConfig,
-  ) => Promise<ApiRateLimitResult>;
-  requireAuthFromRequest: (request: Request) => Promise<TUser>;
-  requireRoleFromRequest: (
-    request: Request,
-    roles: TRole[],
-  ) => Promise<TUser>;
-  errorResponse: (
-    message: string,
-    status: number,
-    issues?: unknown,
-  ) => Response;
-  handleApiError: (error: unknown) => Response;
-  getRateLimitExceededMessage: () => string;
-  logTiming: (entry: {
-    method: string;
-    path: string;
-    status?: number;
-    durationMs: number;
-    error?: string;
-  }) => void;
-}
-
-export function createApiHandlerFactory<TRole, TRateLimitConfig, TUser>(
-  deps: ApiHandlerFactoryDeps<TRole, TRateLimitConfig, TUser>,
-) {
-  return function createApiHandler<
-    TInput = unknown,
-    TParams extends Record<string, string> = Record<string, string>,
-  >(
-    options: ApiHandlerOptions<
-      TInput,
-      TParams,
-      TRole,
-      TRateLimitConfig,
-      TUser
-    >,
-  ) {
-    return async (
-      request: Request,
-      context: { params: Promise<TParams> },
-    ): Promise<Response> => {
-      const startMs = performance.now();
-      try {
-        let rateLimitHeaders: Record<string, string> | undefined;
-        if (options.rateLimit) {
-          const rateLimitResult = await deps.applyRateLimit(
-            request,
-            options.rateLimit,
-          );
-
-          rateLimitHeaders = {
-            "RateLimit-Limit": String(rateLimitResult.limit),
-            "RateLimit-Remaining": String(rateLimitResult.remaining),
-            "RateLimit-Reset": String(rateLimitResult.reset),
-          };
-
-          if (!rateLimitResult.success) {
-            return new Response(
-              JSON.stringify({
-                success: false,
-                error: deps.getRateLimitExceededMessage(),
-              }),
-              {
-                status: 429,
-                headers: {
-                  "Content-Type": "application/json",
-                  ...rateLimitHeaders,
-                },
-              },
-            );
-          }
-        }
-
-        let user: TUser | undefined;
-        if (options.roles && options.roles.length > 0) {
-          user = await deps.requireRoleFromRequest(request, options.roles);
-        } else if (options.auth) {
-          user = await deps.requireAuthFromRequest(request);
-        }
-
-        let validatedBody: TInput | undefined;
-        if (options.schema) {
-          if (typeof (options.schema as { safeParse?: unknown }).safeParse === "function") {
-            const body = await request.json();
-            const result = options.schema.safeParse(body);
-            if (!result.success) {
-              return deps.errorResponse(
-                "Validation failed",
-                400,
-                result.error.issues,
-              );
-            }
-            validatedBody = result.data;
-          } else {
-            try {
-              validatedBody = (await request.json()) as TInput;
-            } catch {
-              validatedBody = undefined;
-            }
-          }
-        }
-
-        const resolvedParams = (context as { params?: Promise<TParams> })?.params
-          ? await context.params
-          : undefined;
-
-        const response = await options.handler({
-          request,
-          user,
-          body: validatedBody,
-          params: resolvedParams,
-        });
-
-        response.headers.set("Access-Control-Max-Age", "86400");
-
-        if (rateLimitHeaders) {
-          for (const [key, value] of Object.entries(rateLimitHeaders)) {
-            response.headers.set(key, value);
-          }
-        }
-
-        deps.logTiming({
-          method: request.method,
-          path: new URL(request.url).pathname,
-          status: response.status,
-          durationMs: Math.round(performance.now() - startMs),
-        });
-
-        return response;
-      } catch (error) {
-        deps.logTiming({
-          method: request.method,
-          path: new URL(request.url).pathname,
-          durationMs: Math.round(performance.now() - startMs),
-          error: error instanceof Error ? error.message : String(error),
-        });
-
-        return deps.handleApiError(error);
-      }
-    };
-  };
-}

package/src/next/api/errorHandler.ts

@@ -1,125 +0,0 @@
-/**
- * Generic API error handler for Next.js API routes.
- *
- * Framework-agnostic version of the app's handleApiError. Business-specific
- * error classes and loggers are injected via factory options so this module
- * has zero knowledge of Firebase, Resend, or letitrip.in domain logic.
- *
- * @example
- * ```ts
- * // apps/web/src/lib/api/error-handler.ts
- * import { createApiErrorHandler } from '..';
- * import { AppError } from '@/lib/errors';
- * import { serverLogger } from '@/lib/server-logger';
- *
- * export const handleApiError = createApiErrorHandler({
- *   isAppError: (e): e is AppError => e instanceof AppError,
- *   getStatusCode: (e) => e.statusCode,
- *   toJSON: (e) => e.toJSON(),
- *   logger: serverLogger,
- *   internalErrorCode: 'GEN_INTERNAL_ERROR',
- *   internalErrorMessage: 'An internal server error occurred',
- * });
- * ```
- */
-
-import { NextResponse } from "next/server.js";
-
-/** Minimal logger interface — satisfied by Winston, Pino, or console. */
-export interface IApiErrorLogger {
-  error(message: string, meta?: Record<string, unknown>): void;
-}
-
-/** Options for createApiErrorHandler factory. */
-export interface ApiErrorHandlerOptions<TAppError> {
-  /**
-   * Type guard — returns true when the thrown value is your app's AppError
-   * (or any subclass) that has statusCode / toJSON methods.
-   */
-  isAppError(err: unknown): err is TAppError;
-
-  /** Extract the HTTP status code from your AppError. */
-  getStatusCode(err: TAppError): number;
-
-  /** Serialise the error to a JSON-safe shape for the response body. */
-  toJSON(err: TAppError): unknown;
-
-  /** Logger used for 5xx and unexpected errors. */
-  logger: IApiErrorLogger;
-
-  /** Error code included in the 500 response body. */
-  internalErrorCode?: string;
-
-  /** Error message included in the 500 response body. */
-  internalErrorMessage?: string;
-}
-
-/**
- * Build a typed handleApiError function bound to your app's error hierarchy.
- *
- * The returned function:
- * - Returns a typed NextResponse for known AppError subclasses.
- * - Returns a 400 with validation details for Zod-like error shapes.
- * - Logs unexpected errors server-side; returns a generic 500 (no stack trace
- *   leaks to the client).
- */
-export function createApiErrorHandler<TAppError>(
-  options: ApiErrorHandlerOptions<TAppError>,
-) {
-  const {
-    isAppError,
-    getStatusCode,
-    toJSON,
-    logger,
-    internalErrorCode = "INTERNAL_ERROR",
-    internalErrorMessage = "An internal server error occurred",
-  } = options;
-
-  return function handleApiError(error: unknown): NextResponse {
-    // Known AppError subclass — structured response
-    if (isAppError(error)) {
-      const status = getStatusCode(error);
-      if (status >= 500) {
-        logger.error("API Error", {
-          body: toJSON(error) as Record<string, unknown>,
-        });
-      }
-      return NextResponse.json(toJSON(error), { status });
-    }
-
-    // Zod / similar validation error shape: { issues: [...] }
-    if (
-      error !== null &&
-      typeof error === "object" &&
-      "issues" in error &&
-      Array.isArray((error as Record<string, unknown>).issues)
-    ) {
-      return NextResponse.json(
-        {
-          success: false,
-          error: "Validation failed",
-          code: "VALIDATION_ERROR",
-          data: error,
-        },
-        { status: 400 },
-      );
-    }
-
-    // Unknown / unexpected error — log full details, return generic 500
-    logger.error("Unexpected API error", {
-      error:
-        error instanceof Error
-          ? { name: error.name, message: error.message, stack: error.stack }
-          : error,
-    });
-
-    return NextResponse.json(
-      {
-        success: false,
-        error: internalErrorMessage,
-        code: internalErrorCode,
-      },
-      { status: 500 },
-    );
-  };
-}

package/src/next/api/routeHandler.ts

@@ -1,175 +0,0 @@
-/**
- * createRouteHandler — provider-aware API route handler factory for feat-* packages.
- *
- * Works like letitrip.in's local `createApiHandler` but uses `getProviders().session`
- * for auth instead of a hardwired Firebase Admin call. This makes it portable across
- * all consumer projects that register an `ISessionProvider`.
- *
- * @example
- * ```ts
- * export const POST = createRouteHandler({
- *   auth: true,
- *   roles: ["admin"],
- *   schema: mySchema,
- *   handler: async ({ user, body }) => { ... },
- * });
- * ```
- */
-
-import { NextResponse } from "next/server.js";
-import { getProviders } from "../../contracts";
-
-/** Minimal schema interface compatible with Zod v3 and v4. */
-interface ParseableSchema<TOutput> {
-  safeParse(
-    data: unknown,
-  ):
-    | { success: true; data: TOutput }
-    | { success: false; error: { issues?: unknown[] } };
-}
-
-export interface RouteUser {
-  uid: string;
-  email?: string | null;
-  role?: string;
-  [key: string]: unknown;
-}
-
-interface RouteHandlerOptions<
-  TInput = unknown,
-  TParams = Record<string, string>,
-> {
-  /** Require a valid session cookie. Implied when `roles` is set. */
-  auth?: boolean;
-  /**
-   * If provided, the verified user's `role` must be in this list.
-   * Implies `auth: true`.
-   */
-  roles?: string[];
-  /** Zod schema to validate + parse the JSON request body. */
-  schema?: ParseableSchema<TInput>;
-  /** Route handler. `user` is present when `auth: true`. */
-  handler: (ctx: {
-    request: Request;
-    user?: RouteUser;
-    body?: TInput;
-    params?: TParams;
-  }) => Promise<Response>;
-}
-
-/** Read the `__session` HTTP-only cookie from request headers. */
-function readSessionCookie(request: Request): string | null {
-  const cookieHeader = request.headers.get("cookie") ?? "";
-  const match = cookieHeader.match(/(?:^|;\s*)__session=([^;]+)/);
-  return match ? decodeURIComponent(match[1]) : null;
-}
-
-/**
- * Verify the session cookie using `getProviders().session`.
- * Returns a `RouteUser` on success, or throws for invalid credentials.
- */
-async function verifySession(request: Request): Promise<RouteUser> {
-  const { session } = getProviders();
-  if (!session) {
-    throw Object.assign(new Error("Session provider not configured"), {
-      status: 503,
-    });
-  }
-  const cookie = readSessionCookie(request);
-  if (!cookie) {
-    throw Object.assign(new Error("Authentication required"), { status: 401 });
-  }
-  try {
-    const payload = await session.verifySession(cookie);
-    return {
-      uid: payload.uid,
-      email: payload.email,
-      role: payload.role,
-      emailVerified: payload.emailVerified,
-      ...payload.claims,
-    };
-  } catch {
-    throw Object.assign(new Error("Invalid or expired session"), {
-      status: 401,
-    });
-  }
-}
-
-/**
- * Create a typed Next.js App Router handler with built-in auth + Zod validation.
- */
-export function createRouteHandler<
-  TInput = unknown,
-  TParams = Record<string, string>,
->(options: RouteHandlerOptions<TInput, TParams>) {
-  return async (
-    request: Request,
-    context: { params: Promise<TParams> },
-  ): Promise<Response> => {
-    try {
-      // ── Auth ──────────────────────────────────────────────────────────────
-      let user: RouteUser | undefined;
-      const needsAuth =
-        options.auth || (options.roles && options.roles.length > 0);
-
-      if (needsAuth) {
-        user = await verifySession(request);
-      }
-
-      if (options.roles && options.roles.length > 0) {
-        if (!user || !options.roles.includes(user.role ?? "")) {
-          return NextResponse.json(
-            { success: false, error: "Insufficient permissions" },
-            { status: 403 },
-          );
-        }
-      }
-
-      // ── Body validation ───────────────────────────────────────────────────
-      let body: TInput | undefined;
-      if (options.schema) {
-        let raw: unknown;
-        try {
-          raw = await request.json();
-        } catch {
-          return NextResponse.json(
-            { success: false, error: "Invalid JSON body" },
-            { status: 400 },
-          );
-        }
-        const result = options.schema.safeParse(raw);
-        if (!result.success) {
-          return NextResponse.json(
-            {
-              success: false,
-              error: "Validation failed",
-              issues: result.error.issues ?? [],
-            },
-            { status: 400 },
-          );
-        }
-        body = result.data;
-      }
-
-      // ── Params ────────────────────────────────────────────────────────────
-      const params = context?.params ? await context.params : undefined;
-
-      return await options.handler({
-        request,
-        user,
-        body,
-        params: params as TParams | undefined,
-      });
-    } catch (err: unknown) {
-      // Structured errors thrown with .status
-      const status =
-        typeof (err as { status?: unknown })?.status === "number"
-          ? (err as { status: number }).status
-          : 500;
-      const message =
-        err instanceof Error ? err.message : "Internal server error";
-      console.error(`[createRouteHandler] ${request.method} failed`, err);
-      return NextResponse.json({ success: false, error: message }, { status });
-    }
-  };
-}

package/src/next/cache-middleware.ts

@@ -1,112 +0,0 @@
-/**
- * API Response Cache Middleware
- *
- * Wraps a Next.js API handler with in-memory response caching via CacheManager.
- *
- * @example
- * ```ts
- * export const GET = withCache(
- *   async (request) => { ... return NextResponse.json(data); },
- *   { ttl: 5 * 60 * 1000 }
- * );
- * ```
- */
-
-import type { NextRequest } from "next/server.js";
-import { NextResponse } from "next/server.js";
-import { CacheManager } from "../core";
-
-export interface CacheConfig {
-  /** Time to live in milliseconds. Default: 5 minutes. */
-  ttl?: number;
-  /** Include query string in cache key. Default: true. */
-  includeQuery?: boolean;
-  /** Custom cache key generator. */
-  keyGenerator?: (request: NextRequest) => string;
-  /** Bypass caching entirely. Default: false. */
-  bypassCache?: boolean;
-  /** Only cache for these HTTP methods. Default: ['GET']. */
-  methods?: string[];
-}
-
-const DEFAULT_TTL = 5 * 60 * 1000;
-const cache = CacheManager.getInstance(500);
-
-function buildCacheKey(request: NextRequest, config: CacheConfig): string {
-  if (config.keyGenerator) return config.keyGenerator(request);
-  const url = new URL(request.url);
-  if (config.includeQuery !== false && url.search)
-    return `${url.pathname}${url.search}`;
-  return url.pathname;
-}
-
-function isCacheable(request: NextRequest, config: CacheConfig): boolean {
-  if (config.bypassCache) return false;
-  const methods = config.methods ?? ["GET"];
-  return methods.includes(request.method);
-}
-
-type Handler = (
-  request: NextRequest,
-  ...args: unknown[]
-) => Promise<NextResponse>;
-
-export function withCache(handler: Handler, config: CacheConfig = {}): Handler {
-  return async (
-    request: NextRequest,
-    ...args: unknown[]
-  ): Promise<NextResponse> => {
-    if (!isCacheable(request, config)) {
-      return handler(request, ...args);
-    }
-
-    const key = buildCacheKey(request, config);
-    const cached = cache.get<{
-      body: string;
-      status: number;
-      headers: Record<string, string>;
-    }>(key);
-    if (cached) {
-      return new NextResponse(cached.body, {
-        status: cached.status,
-        headers: cached.headers,
-      });
-    }
-
-    const response = await handler(request, ...args);
-    const body = await response.text();
-    const headers: Record<string, string> = {};
-    response.headers.forEach((value, key) => {
-      headers[key] = value;
-    });
-
-    cache.set(
-      key,
-      { body, status: response.status, headers },
-      { ttl: config.ttl ?? DEFAULT_TTL },
-    );
-
-    return new NextResponse(body, { status: response.status, headers });
-  };
-}
-
-/**
- * Invalidate cache entries by key prefix or regex pattern.
- * Pass no argument to clear the entire cache.
- */
-export function invalidateCache(pattern?: string | RegExp): void {
-  if (!pattern) {
-    cache.clear();
-    return;
-  }
-  const keys = cache.keys();
-  if (typeof pattern === "string") {
-    for (const key of keys) {
-      if (key.startsWith(pattern)) cache.delete(key);
-    }
-  } else {
-    for (const key of keys) {
-      if (pattern.test(key)) cache.delete(key);
-    }
-  }
-}