feat: integrate timezone utilities from Kogotochki (PR #39)

- Added @date-fns/tz dependency for timezone support
- Implemented TimezoneUtils class with production-tested functionality
- Created TimezoneFactory with caching for performance
- Added bot-specific formatting methods (formatBotDateTime, formatBotTime)
- Includes business hours checking and next occurrence calculation
- Comprehensive test suite (21 tests passing)
- Documentation with usage examples and patterns
- Production validated: 30+ days in Kogotochki bot (Thailand market)

Benefits:
- 📍 Global user support with proper timezone handling
- 🕐 Clear local time display for all users
- 💼 Business hours support for support/operations
- 🎯 Accurate scheduling for notifications and events
- 🚀 Optimized with instance caching

This addresses timezone issues for global bot deployments.

Author: talkstream

src/lib/utils/examples/timezone-bot-usage.ts

@@ -216,25 +216,25 @@ export class TimezoneAwareBot {
     return { id: userId, timezone: 'Asia/Bangkok' };
   }
 
-  private async processUpdate(ctx: Context) {
+  private async processUpdate(_ctx: Context) {
     // Handle update...
   }
 }
 
 // Helper functions (mock implementations)
-async function getUserFromDB(userId: string): Promise<any> {
-  return { id: userId, timezone: 'Asia/Bangkok' };
+async function getUserFromDB(_userId: string): Promise<any> {
+  return { id: _userId, timezone: 'Asia/Bangkok' };
 }
 
-async function getPaymentHistory(userId: string): Promise<any[]> {
+async function getPaymentHistory(_userId: string): Promise<any[]> {
   return [{ timestamp: new Date(), amount: 100, description: 'Service payment' }];
 }
 
-async function updateUserTimezone(userId: number, timezone: string): Promise<void> {
+async function updateUserTimezone(_userId: number, _timezone: string): Promise<void> {
   // Update in database
 }
 
-async function getTimezoneFromCoordinates(lat: number, lng: number): Promise<string> {
+async function getTimezoneFromCoordinates(_lat: number, _lng: number): Promise<string> {
   // In real app, use Google Timezone API or similar
   return 'Asia/Bangkok';
 }

src/lib/utils/timezone.ts

@@ -6,7 +6,7 @@
  */
 
 import { format as dateFnsFormat, parse, isValid } from 'date-fns';
-import { tz, type TZDate } from '@date-fns/tz';
+import { tz } from '@date-fns/tz';
 
 /**
  * Create timezone-aware date utilities for any timezone
@@ -19,12 +19,10 @@ import { tz, type TZDate } from '@date-fns/tz';
  * ```
  */
 export class TimezoneUtils {
-  private timezone: TZDate;
   private timezoneName: string;
 
   constructor(timezoneName: string = 'UTC') {
     this.timezoneName = timezoneName;
-    this.timezone = tz(timezoneName);
   }
 
   /**
@@ -38,7 +36,7 @@ export class TimezoneUtils {
       return 'Invalid date';
     }
 
-    return dateFnsFormat(dateObj, formatStr, { in: this.timezone });
+    return dateFnsFormat(dateObj, formatStr, { in: tz(this.timezoneName) });
   }
 
   /**
@@ -160,7 +158,11 @@ export class TimezoneFactory {
     if (!this.instances.has(timezone)) {
       this.instances.set(timezone, new TimezoneUtils(timezone));
     }
-    return this.instances.get(timezone)!;
+    const instance = this.instances.get(timezone);
+    if (!instance) {
+      throw new Error(`Failed to create timezone instance for ${timezone}`);
+    }
+    return instance;
   }
 
   /**