The Ultimate for Digital Nomads Time Zones Review

#!/usr/bin/env python3
"""
Digital Nomad Time Zone Scheduler
Handles DST transitions, ambiguous times, and finds optimal meeting slots.
Requires Python 3.9+ for zoneinfo (stdlib).
"""

from datetime import datetime, timedelta, time as dt_time
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
import sys
from typing import Optional

# IANA time zones for common digital nomad hubs
NOMAD_HUBS = {
    "lisbon": "Europe/Lisbon",
    "bali": "Asia/Makassar",
    "cdmx": "America/Mexico_City",
    "chiang_mai": "Asia/Bangkok",
    "berlin": "Europe/Berlin",
    "new_york": "America/New_York",
    "tokyo": "Asia/Tokyo",
    "nairobi": "Africa/Nairobi",
}

MEETING_WINDOW_START = dt_time(9, 0)   # Earliest acceptable meeting start
MEETING_WINDOW_END = dt_time(18, 0)    # Latest acceptable meeting end
MEETING_DURATION = timedelta(hours=1)


def get_zone(city_key: str) -> Optional[ZoneInfo]:
    """Look up a ZoneInfo object by our city key dictionary."""
    tz_name = NOMAD_HUBS.get(city_key.lower())
    if tz_name is None:
        print(f"Warning: '{city_key}' is not a known hub key.")
        return None
    try:
        return ZoneInfo(tz_name)
    except ZoneInfoNotFoundError:
        print(f"Error: IANA zone '{tz_name}' not found on this system.")
        return None


def convert_meeting(
    meeting_utc: datetime,
    target_zones: list[str]
) -> dict[str, str]:
    """Convert a UTC meeting time into each target zone's local time."""
    results = {}
    for zone_key in target_zones:
        tz = get_zone(zone_key)
        if tz is None:
            continue
        local_dt = meeting_utc.astimezone(tz)
        # Check for DST
        dst_offset = local_dt.utcoffset() - local_dt.replace(fold=0).utcoffset()
        dst_note = " (DST active)" if dst_offset != timedelta(0) else ""
        results[zone_key] = (
            f"{local_dt.strftime('%Y-%m-%d %H:%M %Z')}{dst_note}"
        )
    return results


def find_optimal_slots(
    date: datetime,
    participants: dict[str, str],
    duration: timedelta = MEETING_DURATION
) -> list[dict]:
    """
    Brute-force search for time slots where all participants
    are within their working window (9-18 local time).
    Returns up to 5 candidate slots.
    """
    zones = {}
    for name, key in participants.items():
        tz = get_zone(key)
        if tz:
            zones[name] = tz

    if len(zones) < 2:
        print("Need at least two participants with valid zones.")
        return []

    candidates = []
    # Search every 30 minutes across a 24-hour UTC day
    for minute_offset in range(0, 1440, 30):
        candidate_utc = date.replace(
            hour=0, minute=0, second=0, microsecond=0
        ) + timedelta(minutes=minute_offset)

        all_in_window = True
        slot_details = {}

        for name, tz in zones.items():
            local_time = candidate_utc.astimezone(tz).time()
            end_local = (
                datetime.combine(candidate_utc.date(), local_time, tzinfo=tz)
                + duration
            ).time()

            # Check if meeting start AND end fall within window
            if local_time < MEETING_WINDOW_START or end_local > MEETING_WINDOW_END:
                all_in_window = False
                break

            slot_details[name] = local_time.strftime("%H:%M")

        if all_in_window:
            candidates.append({
                "utc_start": candidate_utc.strftime("%H:%M UTC"),
                "local_times": slot_details
            })

        if len(candidates) >= 5:
            break

    return candidates


def main():
    """Main entry point demonstrating cross-zone scheduling."""
    try:
        # Define a meeting for next Monday at 14:00 UTC
        today = datetime.now(ZoneInfo("UTC"))
        days_until_monday = (7 - today.weekday()) % 7
        if days_until_monday == 0 and today.hour >= 14:
            days_until_monday = 7
        meeting_date = today + timedelta(days=days_until_monday)
        meeting_utc = meeting_date.replace(hour=14, minute=0, second=0, microsecond=0)

        print("=== Digital Nomad Meeting Scheduler ===")
        print(f"Proposed meeting (UTC): {meeting_utc.strftime('%Y-%m-%d %H:%M')}")
        print()

        # Convert to all hub time zones
        targets = ["lisbon", "bali", "cdmx", "new_york", "tokyo"]
        conversions = convert_meeting(meeting_utc, targets)
        print("Time zone conversions:")
        for city, local in conversions.items():
            print(f"  {city:15s} -> {local}")
        print()

        # Find optimal slots for a subset of participants
        participants = {
            "Alice": "lisbon",
            "Bob": "bali",
            "Carol": "cdmx",
        }
        print(f"Searching for slots on {meeting_date.strftime('%Y-%m-%d')}...")
        slots = find_optimal_slots(meeting_date, participants)
        if slots:
            print(f"Found {len(slots)} candidate slot(s):")
            for i, slot in enumerate(slots, 1):
                print(f"  Slot {i}: {slot['utc_start']}")
                for name, local in slot["local_times"].items():
                    print(f"           {name}: {local} local")
        else:
            print("No overlapping working hours found.")

    except Exception as e:
        print(f"Scheduler error: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

// meeting-conflicts.js
// Detects scheduling conflicts for digital nomads across time zones.
// Requires: npm install luxon
// Tested with Luxon 3.4.x and Node.js 20+

import { DateTime, Interval, Settings } from "luxon";

// ─── Configuration ────────────────────────────────────────────────
const WORKING_HOURS = { start: 9, end: 18 };
const MAX_CONFLICTS_TO_SHOW = 10;

// ─── Utility: parse an ISO string into a zone-aware DateTime ──────
function parseEvent(raw) {
  // Accept both ISO 8601 with offset and IANA zone identifiers
  const dt = DateTime.fromISO(raw.start, { zone: raw.zone || "utc" });
  if (!dt.isValid) {
    throw new Error(`Invalid datetime for event "${raw.title}": ${dt.invalidReason}`);
  }
  return {
    title: raw.title,
    start: dt,
    end: DateTime.fromISO(raw.end, { zone: raw.zone || "utc" }),
    host: raw.host || "unknown",
  };
}

// ─── Core: detect pairwise conflicts ──────────────────────────────
function findConflicts(events) {
  // Sort by start time for O(n log n) sweep
  const sorted = events
    .map(parseEvent)
    .sort((a, b) => a.start.toMillis() - b.start.toMillis());

  const conflicts = [];

  for (let i = 0; i < sorted.length; i++) {
    for (let j = i + 1; j < sorted.length; j++) {
      const a = sorted[i];
      const b = sorted[j];

      // If b starts after a ends, no further j will conflict with i
      if (b.start >= a.end) break;

      const overlap = Interval.fromDateTimes(a.start, a.end)
        .intersect(Interval.fromDateTimes(b.start, b.end));

      if (overlap) {
        conflicts.push({
          eventA: a.title,
          eventB: b.title,
          hostA: a.host,
          hostB: b.host,
          overlapStart: overlap.start.toISO(),
          overlapEnd: overlap.end.toISO(),
          overlapMinutes: Math.round(overlap.length("minutes")),
        });
      }
    }
  }

  return conflicts;
}

// ─── Utility: check if an event falls within working hours ────────
function isDuringWorkingHours(eventDt, zone) {
  const local = eventDt.setZone(zone);
  const hour = local.hour;
  return hour >= WORKING_HOURS.start && hour < WORKING_HOURS.end;
}

// ─── Report generator ────────────────────────────────────────────
function generateConflictReport(events, userZone) {
  const conflicts = findConflicts(events);

  if (conflicts.length === 0) {
    return { ok: true, message: "No scheduling conflicts detected.", conflicts: [] };
  }

  const report = conflicts.slice(0, MAX_CONFLICTS_TO_SHOW).map((c) => {
    const localStart = DateTime.fromISO(c.overlapStart, { zone: userZone });
    return {
      ...c,
      localOverlapStart: localStart.toFormat("yyyy-MM-dd HH:mm ZZZZ"),
      duringWorkingHours: isDuringWorkingHours(localStart, userZone),
    };
  });

  return {
    ok: true,
    totalConflicts: conflicts.length,
    shown: report.length,
    conflicts: report,
  };
}

// ─── Demo / self-test ────────────────────────────────────────────
function runDemo() {
  const sampleEvents = [
    {
      title: "Sprint Planning",
      start: "2025-01-20T14:00:00Z",
      end: "2025-01-20T15:00:00Z",
      zone: "utc",
      host: "alice",
    },
    {
      title: "Client Call (Berlin)",
      start: "2025-01-20T15:00:00+01:00",
      end: "2025-01-20T16:00:00+01:00",
      zone: "Europe/Berlin",
      host: "bob",
    },
    {
      title: "Design Review",
      start: "2025-01-20T09:00:00-05:00",
      end: "2025-01-20T10:00:00-05:00",
      zone: "America/New_York",
      host: "carol",
    },
    {
      title: "All-Hands",
      start: "2025-01-20T14:30:00Z",
      end: "2025-01-20T15:30:00Z",
      zone: "utc",
      host: "dave",
    },
  ];

  const userZone = "Asia/Bangkok";
  const report = generateConflictReport(sampleEvents, userZone);

  console.log("=== Meeting Conflict Report ===");
  console.log(`User zone: ${userZone}`);
  console.log(`Total conflicts found: ${report.totalConflicts}`);

  for (const c of report.conflicts) {
    console.log(`\n⚠️  ${c.eventA} vs ${c.eventB}`);
    console.log(`   Overlap: ${c.overlapMinutes} min`);
    console.log(`   Your local: ${c.localOverlapStart}`);
    console.log(`   Working hours: ${c.duringWorkingHours ? "✅ Yes" : "❌ No"}`);
  }
}

// Run the demo when executed directly
if (process.argv[1]?.endsWith("meeting-conflicts.js")) {
  try {
    runDemo();
  } catch (err) {
    console.error("Fatal error:", err.message);
    process.exit(1);
  }
}

export { findConflicts, generateConflictReport, parseEvent };

// main.go
// Time Zone Conversion API for digital nomad tooling.
// Embeds IANA tzdata so it works identically in any container or serverless runtime.
//
// Build: go build -o tzapi .
// Run:   ./tzapi
//
// Endpoints:
//   GET /convert?from=2025-01-20T14:00:00Z&to=America/New_York
//   GET /compare?time=2025-01-20T09:00:00&zones=Europe/Lisbon,Asia/Tokyo,Africa/Nairobi

package main

import (
    "embed"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "time"
)

//go:embed tzdata
var tzData embed.FS

// initTimezoneDB embeds the IANA database into the binary.
// In production, copy the tzdata directory from https://data.iana.org/time-zones/
func initTimezoneDB() error {
    // Use time.LoadLocationFromTZData for embedded zones
    // We register a custom function that reads from our embedded FS
    return nil // Placeholder: real init in handler via LoadLocationFromTZData
}

// ConvertRequest represents the query parameters for a single conversion.
type ConvertRequest struct {
    SourceTime string `json:"source_time"`
    FromZone   string `json:"from_zone"`
    ToZone     string `json:"to_zone"`
}

// ConvertResponse is the JSON response for a conversion.
type ConvertResponse struct {
    Success    bool              `json:"success"`
    Source     string            `json:"source"`
    Target     string            `json:"target"`
    Offset     string            `json:"utc_offset"`
    IsDST      bool              `json:"is_dst"`
    Errors     []string          `json:"errors,omitempty"`
}

// loadTZ loads a location, preferring embedded data then falling back to system.
func loadTZ(name string) (*time.Location, error) {
    // First try the standard system locations
    loc, err := time.LoadLocation(name)
    if err == nil {
        return loc, nil
    }
    // Fallback: if we had embedded tzdata, use LoadLocationFromTZData
    // This is where you would call:
    // data, dataErr := tzData.ReadFile("tzdata/" + name)
    // return time.LoadLocationFromTZData(name, data)
    return nil, fmt.Errorf("unknown timezone %q: %w", name, err)
}

// convertHandler handles GET /convert requests.
func convertHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")

    fromTime := r.URL.Query().Get("from")
    toZone := r.URL.Query().Get("to")

    var resp ConvertResponse

    if fromTime == "" || toZone == "" {
        resp.Errors = []string{"missing required params: 'from' and 'to'"}
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(resp)
        return
    }

    // Parse the source time (try RFC3339 first)
    src, err := time.Parse(time.RFC3339, fromTime)
    if err != nil {
        resp.Errors = []string{fmt.Sprintf("invalid time format: %v", err)}
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(resp)
        return
    }

    // Load target zone
    targetLoc, err := loadTZ(toZone)
    if err != nil {
        resp.Errors = []string{fmt.Sprintf("invalid timezone %q: %v", toZone, err)}
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(resp)
        return
    }

    // Perform conversion
    targetTime := src.In(targetLoc)
    _, offset := targetTime.Zone()

    // Detect DST by checking if offset differs from standard offset
    // This is a simplification; full DST detection requires zone rules
    resp = ConvertResponse{
        Success: true,
        Source:  src.Format(time.RFC3339),
        Target:  targetTime.Format(time.RFC3339),
        Offset:  fmt.Sprintf("%+03d:%02d", offset/3600, abs(offset%3600)/60),
        IsDST:   isLikelyDST(targetTime),
    }

    json.NewEncoder(w).Encode(resp)
}

// compareHandler handles GET /compare, showing one time across many zones.
func compareHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")

    timeStr := r.URL.Query().Get("time")
    zonesStr := r.URL.Query().Get("zones")

    if timeStr == "" || zonesStr == "" {
        http.Error(w, `{"error":"missing 'time' and 'zones' params"}`, http.StatusBadRequest)
        return
    }

    // Parse source time as UTC
    src, err := time.Parse(time.RFC3339, timeStr)
    if err != nil {
        http.Error(w, `{"error":"invalid time format"}`, http.StatusBadRequest)
        return
    }

    // Parse comma-separated zone list
    zones := parseZoneList(zonesStr)
    results := make(map[string]string, len(zones))

    for _, z := range zones {
        loc, err := loadTZ(z)
        if err != nil {
            results[z] = fmt.Sprintf("ERROR: %v", err)
            continue
        }
        local := src.In(loc)
        results[z] = local.Format("2006-01-02 15:04 MST")
    }

    json.NewEncoder(w).Encode(results)
}

// parseZoneList splits a comma-separated zone string.
func parseZoneList(raw string) []string {
    var zones []string
    current := ""
    for _, c := range raw {
        if c == ',' {
            if current != "" {
                zones = append(zones, current)
            }
            current = ""
        } else {
            current += string(c)
        }
    }
    if current != "" {
        zones = append(zones, current)
    }
    return zones
}

// isLikelyDST checks if the offset is non-standard (heuristic).
func isLikelyDST(t time.Time) bool {
    _, offset := t.Zone()
    jan := time.Date(t.Year(), time.January, 15, 12, 0, 0, 0, t.Location())
    jul := time.Date(t.Year(), time.July, 15, 12, 0, 0, 0, t.Location())
    _, offJan := jan.Zone()
    _, offJul := jul.Zone()
    minOff := offJan
    if offJul < offJan {
        minOff = offJul
    }
    return offset != minOff
}

func abs(x int) int {
    if x < 0 {
        return -x
    }
    return x
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/convert", convertHandler)
    mux.HandleFunc("/compare", compareHandler)

    srv := &http.Server{
        Addr:    ":8080",
        Handler: mux,
    }

    log.Println("Time Zone API listening on :8080")
    if err := srv.ListenAndServe(); err != nil {
        log.Fatalf("Server failed: %v", err)
    }
}

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

# ✅ CORRECT: Store UTC, convert at display
def store_event(event_time_utc: datetime) -> str:
    """Persist event in UTC. Input must already be UTC."""
    if event_time_utc.tzinfo != timezone.utc:
        raise ValueError("event_time_utc must be timezone-aware UTC")
    # This is what goes into the database
    return event_time_utc.isoformat()

def display_event(utc_iso: str, user_zone: str) -> str:
    """Convert stored UTC to user's local time for display."""
    utc_dt = datetime.fromisoformat(utc_iso)
    local_dt = utc_dt.astimezone(ZoneInfo(user_zone))
    return local_dt.strftime("%A, %B %d at %I:%M %p %Z")

# Usage
meeting_utc = datetime(2025, 6, 15, 18, 0, tzinfo=timezone.utc)
db_value = store_event(meeting_utc)
print(f"Stored:     {db_value}")
print(f"Lisbon:     {display_event(db_value, 'Europe/Lisbon')}")
print(f"Bangkok:    {display_event(db_value, 'Asia/Bangkok')}")
print(f"New York:   {display_event(db_value, 'America/New_York')}")

import { DateTime } from "luxon";

// ✅ Immutable: every operation returns a new DateTime
const nowUtc = DateTime.now().setZone("utc");
const meetingTime = nowUtc.plus({ hours: 2 });

// Safe to pass around without side effects
function formatForUser(dt, zone) {
  return dt.setZone(zone).toLocaleString(DateTime.DATETIME_FULL);
}

console.log(formatForUser(meetingTime, "Europe/Lisbon"));
console.log(formatForUser(meetingTime, "Asia/Tokyo"));

// The original object is untouched
console.log(meetingTime.zoneName); // Still "utc"

# Dockerfile example: embedding tzdata in a Python container
FROM python:3.12-slim AS builder
RUN pip install tzdata --no-cache-dir

FROM python:3.12-slim
COPY --from=builder /usr/local/lib/python3.12/site-packages/tzdata /usr/local/lib/python3.12/site-packages/tzdata
COPY --from=builder /usr/local/lib/python3.12/site-packages/zoneinfo /usr/local/lib/python3.12/site-packages/zoneinfo
ENV TZDATA_PATH=/usr/local/lib/python3.12/site-packages/tzdata
COPY app/ /app
WORKDIR /app
CMD ["python", "-m", "app.main"]