(SP:1) [Backend] Add env docs and unify structured logging (remove runtime console.*)

Author: liudmylasovetovs

frontend/app/[locale]/shop/admin/products/_components/product-form.tsx

@@ -5,6 +5,7 @@ import { useRouter } from 'next/navigation';
 
 import { CATEGORIES, COLORS, PRODUCT_TYPES, SIZES } from '@/lib/config/catalog';
 import type { ProductAdminInput } from '@/lib/validation/shop';
+import { logError } from '@/lib/logging';
 
 const localSlugify = (input: string): string => {
   return input
@@ -344,10 +345,11 @@ export function ProductForm({
       const destinationSlug = data.product?.slug ?? slugValue;
       router.push(`/shop/products/${destinationSlug}`);
     } catch (err) {
-      console.error(
-        `Failed to ${mode === 'create' ? 'create' : 'update'} product`,
-        err
-      );
+      logError('admin_product_form_failed', err, {
+        mode,
+        productId: productId ?? null,
+        slug: slugValue,
+      });
       setError(
         `Unexpected error while ${
           mode === 'create' ? 'creating' : 'updating'

frontend/app/[locale]/shop/admin/products/page.tsx

@@ -6,6 +6,7 @@ import { db } from '@/db';
 import { products, productPrices } from '@/db/schema';
 import { formatMoney, resolveCurrencyFromLocale } from '@/lib/shop/currency';
 import { fromDbMoney } from '@/lib/shop/money';
+import { logWarn } from '@/lib/logging';
 
 function formatDate(value: Date | null, locale: string) {
   if (!value) return '-';
@@ -22,7 +23,7 @@ function safeFromDbMoney(
   try {
     return fromDbMoney(value);
   } catch (err) {
-    console.warn('[admin products] fromDbMoney failed', {
+    logWarn('admin_products_from_db_money_failed', {
       ...ctx,
       valueType: typeof value,
       value,

frontend/app/[locale]/shop/checkout/payment/StripePaymentClient.tsx

@@ -22,6 +22,7 @@ import {
   resolveCurrencyFromLocale,
   type CurrencyCode,
 } from '@/lib/shop/currency';
+import { logError } from '@/lib/logging';
 
 type PaymentFormProps = {
   orderId: string;
@@ -111,7 +112,7 @@ function StripePaymentForm({ orderId, locale }: PaymentFormProps) {
       });
       router.push(next);
     } catch (error) {
-      console.error('Payment confirmation failed', error);
+      logError('stripe_payment_confirm_failed', error, { orderId });
       setErrorMessage('We couldn’t confirm your payment. Please try again.');
       router.push(`/shop/checkout/error?orderId=${orderId}`);
     } finally {

frontend/app/[locale]/shop/checkout/payment/[orderId]/page.tsx

@@ -8,6 +8,7 @@ import { orderIdParamSchema } from '@/lib/validation/shop';
 import { getStripeEnv } from '@/lib/env/stripe';
 import { createPaymentIntent, retrievePaymentIntent } from '@/lib/psp/stripe';
 import { setOrderPaymentIntent } from '@/lib/services/orders';
+import { logError } from '@/lib/logging';
 
 function getOrderId(params: { orderId?: string }) {
   const parsed = orderIdParamSchema.safeParse({ id: params.orderId ?? '' });
@@ -169,15 +170,11 @@ export default async function PaymentPage(props: PaymentPageProps) {
         clientSecret = created.clientSecret;
       }
     } catch (error) {
-      console.error(
-        'Failed to initialize Stripe payment intent',
-        {
-          orderId: order.id,
-          existingPi,
-          phase,
-        },
-        error
-      );
+      logError('payment_page_failed', error, {
+        orderId: order.id,
+        existingPi,
+        phase,
+      });
 
       // Leave clientSecret empty -> UI shows "Payment cannot be initialized"
     }

frontend/app/api/shop/cart/rehydrate/route.ts

@@ -1,25 +1,26 @@
-import { NextRequest, NextResponse } from "next/server";
+import { NextRequest, NextResponse } from 'next/server';
 
-import { MoneyValueError } from "@/db/queries/shop/orders";
-import { resolveLocaleAndCurrency } from "@/lib/shop/request-locale";
+import { MoneyValueError } from '@/db/queries/shop/orders';
+import { resolveLocaleAndCurrency } from '@/lib/shop/request-locale';
 
-import { rehydrateCartItems } from "@/lib/services/products";
-import { cartRehydratePayloadSchema } from "@/lib/validation/shop";
-import { InvalidPayloadError, PriceConfigError } from "@/lib/services/errors";
+import { rehydrateCartItems } from '@/lib/services/products';
+import { cartRehydratePayloadSchema } from '@/lib/validation/shop';
+import { InvalidPayloadError, PriceConfigError } from '@/lib/services/errors';
+import { logError } from '@/lib/logging';
 
 function normalizeCartPayload(body: unknown) {
-  if (!body || typeof body !== "object") return body;
+  if (!body || typeof body !== 'object') return body;
   const { items, ...rest } = body as { items?: unknown };
 
   if (!Array.isArray(items)) return body;
 
   return {
     ...rest,
-    items: items.map((item) => {
-      if (!item || typeof item !== "object") return item;
+    items: items.map(item => {
+      if (!item || typeof item !== 'object') return item;
       const { quantity, ...itemRest } = item as { quantity?: unknown };
       const normalizedQuantity =
-        typeof quantity === "string" && quantity.trim().length > 0
+        typeof quantity === 'string' && quantity.trim().length > 0
           ? Number(quantity)
           : quantity;
 
@@ -35,7 +36,7 @@ export async function POST(request: NextRequest) {
     body = await request.json();
   } catch {
     return NextResponse.json(
-      { error: "Unable to process cart data." },
+      { error: 'Unable to process cart data.' },
       { status: 400 }
     );
   }
@@ -45,20 +46,19 @@ export async function POST(request: NextRequest) {
 
   if (!parsedPayload.success) {
     return NextResponse.json(
-      { error: "Invalid cart payload", details: parsedPayload.error.format() },
+      { error: 'Invalid cart payload', details: parsedPayload.error.format() },
       { status: 400 }
     );
   }
 
   const { currency } = resolveLocaleAndCurrency(request);
 
-
   try {
     const { items } = parsedPayload.data;
     const parsedResult = await rehydrateCartItems(items, currency);
     return NextResponse.json(parsedResult);
   } catch (error) {
-    console.error("Cart rehydrate failed", error);
+    logError('cart_rehydrate_failed', error);
 
     if (error instanceof PriceConfigError) {
       return NextResponse.json(
@@ -73,8 +73,8 @@ export async function POST(request: NextRequest) {
     if (error instanceof MoneyValueError) {
       return NextResponse.json(
         {
-          code: "PRICE_CONFIG_ERROR",
-          message: "Invalid price configuration for one or more products.",
+          code: 'PRICE_CONFIG_ERROR',
+          message: 'Invalid price configuration for one or more products.',
           details: {
             productId: error.productId,
             field: error.field,
@@ -93,7 +93,7 @@ export async function POST(request: NextRequest) {
     }
 
     return NextResponse.json(
-      { error: "Unable to rehydrate cart." },
+      { error: 'Unable to rehydrate cart.' },
       { status: 500 }
     );
   }

frontend/app/api/shop/internal/orders/restock-stale/route.ts

@@ -1,4 +1,4 @@
-// C:\Users\milka\devlovers.net\frontend\app\api\shop\internal\orders\restock-stale\route.ts
+//app\api\shop\internal\orders\restock-stale\route.ts
 import { NextRequest, NextResponse } from 'next/server';
 import crypto from 'crypto';
 import { sql } from 'drizzle-orm';
@@ -10,6 +10,7 @@ import {
 } from '@/lib/services/orders';
 
 import { requireInternalJanitorAuth } from '@/lib/auth/internal-janitor';
+import { logError } from '@/lib/logging';
 
 export const runtime = 'nodejs';
 
@@ -422,7 +423,7 @@ export async function POST(request: NextRequest) {
       minIntervalSeconds,
     });
   } catch (e) {
-    console.error('restock-stale failed', { runId, error: e });
+    logError('restock_stale_failed', e, { runId });
     return NextResponse.json(
       { success: false, code: 'INTERNAL_ERROR' },
       { status: 500 }

frontend/app/api/shop/webhooks/stripe/route.ts

@@ -6,8 +6,8 @@ import { db } from '@/db';
 import { verifyWebhookSignature, retrieveCharge } from '@/lib/psp/stripe';
 import { orders, stripeEvents } from '@/db/schema';
 import { restockOrder } from '@/lib/services/orders';
-import { logError } from '@/lib/logging';
 import { guardedPaymentStatusUpdate } from '@/lib/services/orders/payment-state';
+import { logError, logInfo, logWarn } from '@/lib/logging';
 
 function warnRefundFullnessUndetermined(payload: {
   eventId: string;
@@ -24,7 +24,7 @@ function warnRefundFullnessUndetermined(payload: {
   refundId?: string | null;
   refundAmount?: number | null;
 }) {
-  console.warn('stripe_webhook_refund_fullness_undetermined', payload);
+  logWarn('stripe_webhook_refund_fullness_undetermined', payload);
 }
 
 function logWebhookEvent(payload: {
@@ -35,7 +35,7 @@ function logWebhookEvent(payload: {
 }) {
   const { orderId, paymentIntentId, paymentStatus, eventType } = payload;
 
-  console.log('stripe_webhook', {
+  logInfo('stripe_webhook', {
     provider: 'stripe',
     orderId,
     paymentIntentId,
@@ -286,7 +286,7 @@ export async function POST(request: NextRequest) {
         .limit(1);
 
       if (existing?.processedAt) {
-        console.log('stripe_webhook_duplicate_event', {
+        logInfo('stripe_webhook_duplicate_event', {
           eventId: event.id,
           eventType,
         });
@@ -310,7 +310,7 @@ export async function POST(request: NextRequest) {
       if (candidates.length === 1) {
         resolvedOrderId = candidates[0].id;
       } else {
-        console.log('stripe_webhook_missing_order_id', {
+        logWarn('stripe_webhook_missing_order_id', {
           paymentIntentId,
           eventType,
           reason:
@@ -353,7 +353,7 @@ export async function POST(request: NextRequest) {
     }
 
     if (order.paymentIntentId && order.paymentIntentId !== paymentIntentId) {
-      console.log('stripe_webhook_payment_intent_mismatch', {
+      logInfo('stripe_webhook_payment_intent_mismatch', {
         orderId: order.id,
         paymentIntentId,
         orderPaymentIntentId: order.paymentIntentId,
@@ -417,7 +417,7 @@ export async function POST(request: NextRequest) {
           })
           .where(eq(orders.id, order.id));
 
-        console.log('stripe_webhook_mismatch', {
+        logWarn('stripe_webhook_mismatch', {
           orderId: order.id,
           paymentIntentId,
           eventType,

frontend/db/index.ts

@@ -1,7 +1,7 @@
 import { neon } from '@neondatabase/serverless';
 import { drizzle } from 'drizzle-orm/neon-http';
 import * as dotenv from 'dotenv';
-
+import { logWarn } from '@/lib/logging';
 import * as schema from './schema';
 
 dotenv.config();
@@ -15,9 +15,7 @@ function resolveDatabaseUrl(): string {
       return process.env.DATABASE_URL_PREVIEW;
     }
     if (process.env.DATABASE_URL) {
-      console.warn(
-        '[db] DATABASE_URL_PREVIEW missing; falling back to DATABASE_URL for preview build.'
-      );
+      logWarn('db_preview_url_fallback', { context });
       return process.env.DATABASE_URL;
     }
     throw new Error('DATABASE_URL_PREVIEW is missing for preview deploys');

frontend/lib/cart.ts

@@ -11,6 +11,7 @@ import {
 } from '@/lib/validation/shop';
 import { fromCents } from '@/lib/shop/money';
 import { createCartItemKey } from '@/lib/shop/cart-item-key';
+import { logWarn } from '@/lib/logging';
 
 const CART_KEY = 'devlovers-cart';
 
@@ -86,7 +87,9 @@ export function getStoredCartItems(): CartClientItem[] {
       .map(item => normalizeStoredItem(item))
       .filter((item): item is CartClientItem => item !== null);
   } catch (error) {
-    console.warn('Failed to read cart from localStorage', error);
+    logWarn('cart_read_failed', {
+      message: error instanceof Error ? error.message : String(error),
+    });
     return [];
   }
 }
@@ -97,7 +100,9 @@ export function persistCartItems(items: CartClientItem[]): void {
   try {
     window.localStorage.setItem(CART_KEY, JSON.stringify(items));
   } catch (error) {
-    console.warn('Failed to save cart', error);
+    logWarn('cart_save_failed', {
+      message: error instanceof Error ? error.message : String(error),
+    });
   }
 }
 

frontend/lib/cloudinary.ts

@@ -1,6 +1,7 @@
-import { v2 as cloudinary } from "cloudinary";
+import { v2 as cloudinary } from 'cloudinary';
 
-import { getCloudinaryEnvRequired } from "@/lib/env/cloudinary";
+import { getCloudinaryEnvRequired } from '@/lib/env/cloudinary';
+import { logError } from '@/lib/logging';
 
 let isConfigured = false;
 
@@ -18,7 +19,7 @@ function ensureConfigured() {
 }
 
 async function toBuffer(fileOrBuffer: File | Buffer): Promise<Buffer> {
-  if (typeof Buffer !== "undefined" && Buffer.isBuffer(fileOrBuffer)) {
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(fileOrBuffer)) {
     return fileOrBuffer;
   }
 
@@ -41,15 +42,18 @@ export async function uploadImage(
     const uploadStream = cloudinary.uploader.upload_stream(
       {
         folder: options?.folder ?? env.uploadFolder,
-        resource_type: "image",
+        resource_type: 'image',
       },
       (
         error: unknown,
         result: { secure_url: string; public_id: string } | undefined
       ) => {
         if (error || !result) {
-          console.error("Cloudinary upload failed", error);
-          reject(new Error("Failed to upload image to Cloudinary"));
+          logError('cloudinary_upload_failed', error, {
+            folder: options?.folder ?? env.uploadFolder,
+            hasResult: Boolean(result),
+          });
+          reject(new Error('Failed to upload image to Cloudinary'));
           return;
         }