refactor(api): apply function style convention across api and web

.cursor/rules/function-style.mdc

@@ -0,0 +1,37 @@
+---
+description: Function style convention — arrow functions for non-components, function declarations for React components; use when writing or reviewing TS/TSX
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# Function Style Convention
+
+Unify function style across the codebase:
+
+## Use arrow functions
+
+For **all non-component code** (helpers, API functions, handlers, mappers, hooks, async functions, etc.):
+
+- **Format**: `const name = (params): ReturnType => { ... }` or `export const name = (params): ReturnType => { ... }`
+- **Async**: `export const name = async (params): Promise<ReturnType> => { ... }`
+- **Single expression**: `const name = (x: T): R => expression;` when the body is a single return.
+
+Examples: `mapHttpError`, `getApiUrl`, `request`, `buildProductsQuery`, `getProducts`, `toUserResponse`, `toListItem`, `healthHandler`, `useNotification`, `useLocalStorage`, `getErrorMessage`, `formatDateTime`, `notifyError`.
+
+## Use `function` declarations
+
+For **React components** (anything that returns JSX or is used as `<Component />`):
+
+- **Format**: `export function ComponentName(props): React.ReactElement` or `function ComponentName(props) { ... }`
+- Keep subcomponents (e.g. `ProductImageUploadField`, `LayoutContent`, `GroupLinks`) and providers (e.g. `NotificationProvider`, `DataBoundary`) as `function` as well.
+
+Examples: `ProductsPage`, `ProductDetailPage`, `DataBoundary`, `ProductEditModal`, `NotificationProvider`, `DefaultLayout`, `AuthGuard`, `SidebarProvider`.
+
+## Summary
+
+| Kind | Style |
+|------|--------|
+| React component / returns JSX | `function Name()` |
+| Everything else (utils, API, handlers, hooks, mappers) | `const name = () =>` |
+
+Preserve existing explicit return types and type annotations when converting.

apps/api/src/app.ts

@@ -205,26 +205,27 @@ const deleteUserRoute = createRoute({
 });
 
 // Single OpenAPIHono with one continuous chain so RPC schema is preserved for hc<AppType>.
+// Handlers are typed as Promise<Response> / Response; OpenAPIHono expects TypedResponse, so cast is required.
 const api = new OpenAPIHono()
   .openapi(healthRoute, healthHandler as unknown as RouteHandler<typeof healthRoute>)
   .openapi(healthLiveRoute, healthLiveHandler as unknown as RouteHandler<typeof healthLiveRoute>)
-  .openapi(listPriceHistoryRoute, listPriceHistoryHandler as RouteHandler<typeof listPriceHistoryRoute>)
-  .openapi(getPriceHistoryByIdRoute, getPriceHistoryByIdHandler as RouteHandler<typeof getPriceHistoryByIdRoute>)
-  .openapi(createPriceHistoryRoute, createPriceHistoryHandler as RouteHandler<typeof createPriceHistoryRoute>)
-  .openapi(listInventoryAdjustmentsRoute, listInventoryAdjustmentsHandler as RouteHandler<typeof listInventoryAdjustmentsRoute>)
-  .openapi(getInventoryAdjustmentByIdRoute, getInventoryAdjustmentByIdHandler as RouteHandler<typeof getInventoryAdjustmentByIdRoute>)
-  .openapi(createInventoryAdjustmentRoute, createInventoryAdjustmentHandler as RouteHandler<typeof createInventoryAdjustmentRoute>)
-  .openapi(listProductsRoute, listProductsHandler as RouteHandler<typeof listProductsRoute>)
-  .openapi(getProductByIdRoute, getProductByIdHandler as RouteHandler<typeof getProductByIdRoute>)
-  .openapi(createProductRoute, createProductHandler as RouteHandler<typeof createProductRoute>)
-  .openapi(updateProductRoute, updateProductHandler as RouteHandler<typeof updateProductRoute>)
-  .openapi(deleteProductRoute, deleteProductHandler as RouteHandler<typeof deleteProductRoute>)
-  .openapi(uploadRoute, uploadHandler as RouteHandler<typeof uploadRoute>)
-  .openapi(listUsersRoute, listUsersHandler as RouteHandler<typeof listUsersRoute>)
-  .openapi(getUserByIdRoute, getUserByIdHandler as RouteHandler<typeof getUserByIdRoute>)
-  .openapi(createUserRoute, createUserHandler as RouteHandler<typeof createUserRoute>)
-  .openapi(updateUserRoute, updateUserHandler as RouteHandler<typeof updateUserRoute>)
-  .openapi(deleteUserRoute, deleteUserHandler as RouteHandler<typeof deleteUserRoute>)
+  .openapi(listPriceHistoryRoute, listPriceHistoryHandler as unknown as RouteHandler<typeof listPriceHistoryRoute>)
+  .openapi(getPriceHistoryByIdRoute, getPriceHistoryByIdHandler as unknown as RouteHandler<typeof getPriceHistoryByIdRoute>)
+  .openapi(createPriceHistoryRoute, createPriceHistoryHandler as unknown as RouteHandler<typeof createPriceHistoryRoute>)
+  .openapi(listInventoryAdjustmentsRoute, listInventoryAdjustmentsHandler as unknown as RouteHandler<typeof listInventoryAdjustmentsRoute>)
+  .openapi(getInventoryAdjustmentByIdRoute, getInventoryAdjustmentByIdHandler as unknown as RouteHandler<typeof getInventoryAdjustmentByIdRoute>)
+  .openapi(createInventoryAdjustmentRoute, createInventoryAdjustmentHandler as unknown as RouteHandler<typeof createInventoryAdjustmentRoute>)
+  .openapi(listProductsRoute, listProductsHandler as unknown as RouteHandler<typeof listProductsRoute>)
+  .openapi(getProductByIdRoute, getProductByIdHandler as unknown as RouteHandler<typeof getProductByIdRoute>)
+  .openapi(createProductRoute, createProductHandler as unknown as RouteHandler<typeof createProductRoute>)
+  .openapi(updateProductRoute, updateProductHandler as unknown as RouteHandler<typeof updateProductRoute>)
+  .openapi(deleteProductRoute, deleteProductHandler as unknown as RouteHandler<typeof deleteProductRoute>)
+  .openapi(uploadRoute, uploadHandler as unknown as RouteHandler<typeof uploadRoute>)
+  .openapi(listUsersRoute, listUsersHandler as unknown as RouteHandler<typeof listUsersRoute>)
+  .openapi(getUserByIdRoute, getUserByIdHandler as unknown as RouteHandler<typeof getUserByIdRoute>)
+  .openapi(createUserRoute, createUserHandler as unknown as RouteHandler<typeof createUserRoute>)
+  .openapi(updateUserRoute, updateUserHandler as unknown as RouteHandler<typeof updateUserRoute>)
+  .openapi(deleteUserRoute, deleteUserHandler as unknown as RouteHandler<typeof deleteUserRoute>)
   .doc('/openapi.json', (c) => {
     const baseUrl = c.req.url.replace(/\/openapi\.json.*$/, '');
     return {

apps/api/src/common/filters/error-handler.ts

@@ -7,7 +7,7 @@ type ErrorLike = Error & { code?: string; statusCode?: number };
 /**
  * Central error handler. Masks internal details in production.
  */
-export function errorHandler(err: ErrorLike, c: Context): Response {
+export const errorHandler = (err: ErrorLike, c: Context): Response => {
   // Log server-side (never expose stack to client in production)
   console.error('[Error]', err.message, env.NODE_ENV === 'development' ? err.stack : '');
 
@@ -29,4 +29,4 @@ export function errorHandler(err: ErrorLike, c: Context): Response {
       : err.message;
 
   return c.json({ error: 'Internal Server Error', message }, 500);
-}
+};

apps/api/src/common/guards/auth.guard.ts

@@ -5,11 +5,11 @@ import { HTTPException } from 'hono/http-exception';
  * Placeholder auth guard. Replace with JWT verification when implementing auth.
  * Usage: app.use('/protected/*', authGuard);
  */
-export async function authGuard(c: Context, next: Next): Promise<void> {
+export const authGuard = async (c: Context, next: Next): Promise<void> => {
   const authHeader = c.req.header('Authorization');
   if (!authHeader?.startsWith('Bearer ')) {
     throw new HTTPException(401, { message: 'Missing or invalid Authorization header' });
   }
   // TODO: verify JWT, set c.set('user', payload)
   await next();
-}
+};

apps/api/src/common/interceptors/logging.ts

@@ -3,12 +3,12 @@ import type { Context, Next } from 'hono';
 /**
  * Request logging interceptor. Log method, path, status, and duration.
  */
-export async function requestLogger(c: Context, next: Next): Promise<void> {
+export const requestLogger = async (c: Context, next: Next): Promise<void> => {
   const start = Date.now();
   await next();
   const ms = Date.now() - start;
   const status = c.res.status;
   const method = c.req.method;
   const path = c.req.path;
   console.info(`[${method}] ${path} ${status} ${ms}ms`);
-}
+};

apps/api/src/config/index.ts

@@ -17,13 +17,13 @@ const envSchema = z.object({
 
 export type Env = z.infer<typeof envSchema>;
 
-function loadEnv(): Env {
+const loadEnv = (): Env => {
   const parsed = envSchema.safeParse(process.env);
   if (!parsed.success) {
     console.error('Invalid environment variables:', parsed.error.flatten().fieldErrors);
     throw new Error('Invalid environment variables');
   }
   return parsed.data;
-}
+};
 
 export const env = loadEnv();

apps/api/src/lib/cloudinary.ts

@@ -0,0 +1,24 @@
+/**
+ * Cloudinary delivery URL transforms for outbound image URLs.
+ * All Cloudinary image URLs must include format optimization (f_auto),
+ * quality adjustment (q_auto), and explicit dimensions with crop mode.
+ */
+
+const CLOUDINARY_UPLOAD_PREFIX = 'res.cloudinary.com/';
+const UPLOAD_PATH = '/image/upload/';
+const TRANSFORMS = 'f_auto,q_auto,w_800,h_600,c_fill';
+
+/**
+ * Applies standard delivery transforms to a Cloudinary image URL.
+ * Inserts f_auto, q_auto, and explicit dimensions (w_800, h_600, c_fill).
+ * Non-Cloudinary URLs are returned unchanged.
+ */
+export const toOptimizedImageUrl = (url: string | null | undefined): string | undefined => {
+  if (url == null || url === '') return undefined;
+  if (!url.includes(CLOUDINARY_UPLOAD_PREFIX) || !url.includes(UPLOAD_PATH)) return url;
+  const insert = `${UPLOAD_PATH}${TRANSFORMS}/`;
+  const afterUpload = url.indexOf(UPLOAD_PATH) + UPLOAD_PATH.length;
+  const alreadyHasTransforms = url.slice(afterUpload, afterUpload + 20).includes('f_auto');
+  if (alreadyHasTransforms) return url;
+  return url.replace(UPLOAD_PATH, insert);
+};

apps/api/src/modules/ecommerce/inventory-adjustment.controller.ts

@@ -21,13 +21,13 @@ type ListQuery = z.infer<typeof listInventoryAdjustmentsQuerySchema>;
 type ParamId = z.infer<typeof inventoryAdjustmentIdParamSchema>;
 type CreateBody = z.infer<typeof createInventoryAdjustmentSchema>;
 
-export async function listInventoryAdjustmentsHandler(c: Context<object, string, { out: { query: ListQuery } }>) {
+export const listInventoryAdjustmentsHandler = async (c: Context<object, string, { out: { query: ListQuery } }>): Promise<Response> => {
   const { page, pageSize, q } = c.req.valid('query');
   const list = await inventoryAdjustmentService.getList(page, pageSize, { q });
   return c.json(list);
-}
+};
 
-export async function getInventoryAdjustmentByIdHandler(c: Context<object, string, { out: { param: ParamId } }>) {
+export const getInventoryAdjustmentByIdHandler = async (c: Context<object, string, { out: { param: ParamId } }>): Promise<Response> => {
   const { id } = c.req.valid('param');
   const item = await inventoryAdjustmentService.getById(id);
   if (!item) {
@@ -37,9 +37,9 @@ export async function getInventoryAdjustmentByIdHandler(c: Context<object, strin
     );
   }
   return c.json(item);
-}
+};
 
-export async function createInventoryAdjustmentHandler(c: Context<object, string, { out: { json: CreateBody } }>) {
+export const createInventoryAdjustmentHandler = async (c: Context<object, string, { out: { json: CreateBody } }>): Promise<Response> => {
   try {
     const body = c.req.valid('json');
     const created = await inventoryAdjustmentService.create(body);
@@ -53,4 +53,4 @@ export async function createInventoryAdjustmentHandler(c: Context<object, string
     }
     throw e;
   }
-}
+};

apps/api/src/modules/ecommerce/inventory-adjustment.repository.ts

@@ -1,7 +1,18 @@
 import type { CreateInventoryAdjustmentInput } from './dto/ecommerce.dto.js';
+import type { InventoryAdjustmentGetPayload } from '../../../generated/prisma/models/InventoryAdjustment.js';
 import { prisma } from '../../lib/prisma.js';
 
-function buildWhere(q?: string) {
+/** Prisma payload for InventoryAdjustment with sku and product included (matches our queries). */
+type InventoryAdjustmentWithSkuAndProduct = InventoryAdjustmentGetPayload<{
+  include: { sku: { include: { product: true } } };
+}>;
+
+type OrCondition =
+  | { sku: { product: { name: { contains: string } } } }
+  | { skuId: number };
+type WhereClause = { OR: OrCondition[] };
+
+const buildWhere = (q?: string): WhereClause | undefined => {
   const qTrim = q?.trim();
   if (!qTrim) return undefined;
   const or: Array<
@@ -10,7 +21,7 @@ function buildWhere(q?: string) {
   const id = /^\d+$/.test(qTrim) ? parseInt(qTrim, 10) : NaN;
   if (!Number.isNaN(id)) or.push({ skuId: id });
   return { OR: or };
-}
+};
 
 /** Sentinel returned by create() when Decrease would make stock negative. */
 export const INSUFFICIENT_STOCK = 'INSUFFICIENT_STOCK' as const;
@@ -23,7 +34,7 @@ export const inventoryAdjustmentRepository = {
     page: number,
     pageSize: number,
     options: { q?: string }
-  ) {
+  ): Promise<{ items: InventoryAdjustmentWithSkuAndProduct[]; total: number }> {
     const where = buildWhere(options.q);
     const skip = (page - 1) * pageSize;
     return prisma.$transaction(async (tx) => {
@@ -41,14 +52,16 @@ export const inventoryAdjustmentRepository = {
     });
   },
 
-  async findById(id: number) {
+  async findById(id: number): Promise<InventoryAdjustmentWithSkuAndProduct | null> {
     return prisma.inventoryAdjustment.findUnique({
       where: { id },
       include: { sku: { include: { product: true } } },
     });
   },
 
-  async create(data: CreateInventoryAdjustmentInput) {
+  async create(
+    data: CreateInventoryAdjustmentInput
+  ): Promise<InventoryAdjustmentWithSkuAndProduct | null | typeof INSUFFICIENT_STOCK> {
     return prisma.$transaction(async (tx) => {
       const sku = await tx.sku.findUnique({
         where: { id: data.skuId },

apps/api/src/modules/ecommerce/inventory-adjustment.service.ts

@@ -28,12 +28,12 @@ type PrismaRow = Awaited<
 >;
 type PrismaRowNonNull = NonNullable<PrismaRow>;
 
-function toListItem(row: PrismaRowNonNull): InventoryAdjustmentListItem {
+const isStringRecord = (v: unknown): v is Record<string, string> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v) && Object.values(v).every((x) => typeof x === 'string');
+
+const toListItem = (row: PrismaRowNonNull): InventoryAdjustmentListItem => {
   const attrs = row.sku.attributes;
-  const skuAttributes =
-    typeof attrs === 'object' && attrs !== null && !Array.isArray(attrs)
-      ? (attrs as Record<string, string>)
-      : {};
+  const skuAttributes = isStringRecord(attrs) ? attrs : {};
   return {
     id: row.id,
     skuId: row.skuId,
@@ -46,7 +46,7 @@ function toListItem(row: PrismaRowNonNull): InventoryAdjustmentListItem {
     productId: row.sku.productId,
     skuAttributes,
   };
-}
+};
 
 /**
  * Business logic only. No HTTP/framework types.

apps/api/src/modules/ecommerce/mappers/enum.mapper.test.ts

@@ -22,9 +22,7 @@ import {
   refundStatusMap,
 } from './enum.mapper.js';
 
-function sorted(values: readonly string[]): string[] {
-  return [...values].sort();
-}
+const sorted = (values: readonly string[]): string[] => [...values].sort();
 
 describe('ecommerce enum mappings', () => {
   it('stays consistent with API ecommerce product statuses', () => {

apps/api/src/modules/ecommerce/mappers/enum.mapper.ts

@@ -80,42 +80,31 @@ export const refundStatusMap = {
   Failed: 'Failed',
 } as const satisfies Record<PrismaRefundStatus, RefundStatus>;
 
-export function toSharedProductStatus(status: PrismaProductStatus): ProductStatus {
-  return productStatusMap[status];
-}
+export const toSharedProductStatus = (status: PrismaProductStatus): ProductStatus =>
+  productStatusMap[status];
 
-export function toSharedDiscountType(type: PrismaDiscountType): DiscountType {
-  return discountTypeMap[type];
-}
+export const toSharedDiscountType = (type: PrismaDiscountType): DiscountType =>
+  discountTypeMap[type];
 
-export function toSharedOrderStatus(status: PrismaOrderStatus): OrderStatus {
-  return orderStatusMap[status];
-}
+export const toSharedOrderStatus = (status: PrismaOrderStatus): OrderStatus =>
+  orderStatusMap[status];
 
-export function toSharedPaymentStatus(status: PrismaPaymentStatus): PaymentStatus {
-  return paymentStatusMap[status];
-}
+export const toSharedPaymentStatus = (status: PrismaPaymentStatus): PaymentStatus =>
+  paymentStatusMap[status];
 
-export function toSharedInventoryAdjustmentType(
+export const toSharedInventoryAdjustmentType = (
   type: PrismaInventoryAdjustmentType,
-): InventoryAdjustmentType {
-  return inventoryAdjustmentTypeMap[type];
-}
+): InventoryAdjustmentType => inventoryAdjustmentTypeMap[type];
 
-export function toSharedPaymentMethod(method: PrismaPaymentMethod): PaymentMethod {
-  return paymentMethodMap[method];
-}
+export const toSharedPaymentMethod = (method: PrismaPaymentMethod): PaymentMethod =>
+  paymentMethodMap[method];
 
-export function toSharedPaymentTransactionStatus(
+export const toSharedPaymentTransactionStatus = (
   status: PrismaPaymentTransactionStatus,
-): PaymentTransactionStatus {
-  return paymentTransactionStatusMap[status];
-}
+): PaymentTransactionStatus => paymentTransactionStatusMap[status];
 
-export function toSharedPromotionStatus(status: PrismaPromotionStatus): PromotionStatusValue {
-  return promotionStatusMap[status];
-}
+export const toSharedPromotionStatus = (status: PrismaPromotionStatus): PromotionStatusValue =>
+  promotionStatusMap[status];
 
-export function toSharedRefundStatus(status: PrismaRefundStatus): RefundStatus {
-  return refundStatusMap[status];
-}
+export const toSharedRefundStatus = (status: PrismaRefundStatus): RefundStatus =>
+  refundStatusMap[status];