@jmruthers/pace-core 0.5.184 → 0.5.186

package/src/utils/location/location.ts

@@ -0,0 +1,175 @@
+/**
+ * @file Location Utilities
+ * @package @jmruthers/pace-core
+ * @module Utils/Location
+ * @since 0.1.0
+ *
+ * Utility functions for working with geographic coordinates.
+ * Provides functions for formatting, validating, comparing, and generating URLs for coordinates.
+ *
+ * Features:
+ * - Format coordinates for display
+ * - Validate coordinate objects
+ * - Compare coordinates with tolerance
+ * - Generate Google Maps URLs
+ *
+ * @example
+ * ```ts
+ * import { formatCoordinates, hasValidCoordinates, areCoordinatesEqual, getGoogleMapsUrl } from '@jmruthers/pace-core/utils/location';
+ *
+ * const coords = { lat: -37.8136, lng: 144.9631 };
+ *
+ * // Format for display
+ * formatCoordinates(coords); // "-37.813600, 144.963100"
+ *
+ * // Validate
+ * hasValidCoordinates(coords); // true
+ *
+ * // Compare
+ * areCoordinatesEqual(coords, { lat: -37.8137, lng: 144.9632 }); // true (within tolerance)
+ *
+ * // Generate Google Maps URL
+ * getGoogleMapsUrl(coords); // "https://www.google.com/maps/search/?api=1&query=-37.8136,144.9631"
+ * ```
+ */
+
+/**
+ * Coordinate interface for latitude and longitude
+ */
+export interface Coordinates {
+  lat: number;
+  lng: number;
+}
+
+/**
+ * Format coordinates as a string with 6 decimal places
+ *
+ * @param coords - Coordinate object with lat and lng
+ * @returns Formatted string "lat, lng" or "N/A" if invalid
+ *
+ * @example
+ * ```ts
+ * formatCoordinates({ lat: -37.8136, lng: 144.9631 });
+ * // "-37.813600, 144.963100"
+ *
+ * formatCoordinates(undefined);
+ * // "N/A"
+ * ```
+ */
+export function formatCoordinates(coords?: Coordinates): string {
+  if (!coords || typeof coords.lat !== 'number' || typeof coords.lng !== 'number') {
+    return 'N/A';
+  }
+
+  if (!isFinite(coords.lat) || !isFinite(coords.lng)) {
+    return 'N/A';
+  }
+
+  return `${coords.lat.toFixed(6)}, ${coords.lng.toFixed(6)}`;
+}
+
+/**
+ * Check if coordinates are valid
+ *
+ * @param coords - Coordinate object to validate
+ * @returns true if coordinates are valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * hasValidCoordinates({ lat: -37.8136, lng: 144.9631 }); // true
+ * hasValidCoordinates({ lat: 91, lng: 0 }); // false (lat out of range)
+ * hasValidCoordinates(undefined); // false
+ * ```
+ */
+export function hasValidCoordinates(coords?: { lat?: number; lng?: number }): boolean {
+  if (!coords) {
+    return false;
+  }
+
+  const { lat, lng } = coords;
+
+  if (typeof lat !== 'number' || typeof lng !== 'number') {
+    return false;
+  }
+
+  if (!isFinite(lat) || !isFinite(lng)) {
+    return false;
+  }
+
+  // Latitude must be between -90 and 90
+  if (lat < -90 || lat > 90) {
+    return false;
+  }
+
+  // Longitude must be between -180 and 180
+  if (lng < -180 || lng > 180) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if two coordinates are equal within a tolerance
+ *
+ * @param coords1 - First coordinate object
+ * @param coords2 - Second coordinate object
+ * @param tolerance - Tolerance in degrees (default: 0.0001° ≈ 11 meters)
+ * @returns true if coordinates are within tolerance, false otherwise
+ *
+ * @example
+ * ```ts
+ * const coords1 = { lat: -37.8136, lng: 144.9631 };
+ * const coords2 = { lat: -37.8137, lng: 144.9632 };
+ * areCoordinatesEqual(coords1, coords2); // true (within default tolerance)
+ * areCoordinatesEqual(coords1, coords2, 0.00001); // false (stricter tolerance)
+ * ```
+ */
+export function areCoordinatesEqual(
+  coords1: Coordinates | null | undefined,
+  coords2: Coordinates | null | undefined,
+  tolerance: number = 0.0001
+): boolean {
+  // Both null/undefined are considered equal
+  if (!coords1 && !coords2) {
+    return true;
+  }
+
+  // One null/undefined and one not are not equal
+  if (!coords1 || !coords2) {
+    return false;
+  }
+
+  // Validate both coordinates
+  if (!hasValidCoordinates(coords1) || !hasValidCoordinates(coords2)) {
+    return false;
+  }
+
+  // Check if within tolerance (with small epsilon for floating point precision)
+  const epsilon = 1e-10;
+  const latDiff = Math.abs(coords1.lat - coords2.lat);
+  const lngDiff = Math.abs(coords1.lng - coords2.lng);
+
+  return latDiff <= tolerance + epsilon && lngDiff <= tolerance + epsilon;
+}
+
+/**
+ * Generate a Google Maps search URL for coordinates
+ *
+ * @param coords - Coordinate object with lat and lng
+ * @returns Google Maps search URL or empty string if invalid
+ *
+ * @example
+ * ```ts
+ * getGoogleMapsUrl({ lat: -37.8136, lng: 144.9631 });
+ * // "https://www.google.com/maps/search/?api=1&query=-37.8136,144.9631"
+ * ```
+ */
+export function getGoogleMapsUrl(coords?: Coordinates): string {
+  if (!coords || !hasValidCoordinates(coords)) {
+    return '';
+  }
+
+  return `https://www.google.com/maps/search/?api=1&query=${coords.lat},${coords.lng}`;
+}
+

package/src/utils/security/secureDataAccess.ts

@@ -102,7 +102,7 @@ export const createSecureDataAccess = (
       'cake_meal', 'cake_mealtype', 'pace_person', 'pace_member',
       // SECURITY: Phase 3A additions - medical and personal data
       'medi_profile', 'medi_condition', 'medi_diet', 'medi_action_plan', 'medi_profile_versions',
-      'pace_consent', 'pace_contact', 'pace_id_documents', 'pace_qualifications',
+      'pace_consent', 'pace_contact', 'pace_identification', 'pace_identification_type', 'pace_qualification',
       'form_responses', 'form_response_values', 'forms',
       // SECURITY: Phase 3B additions - remaining critical tables
       'invoice', 'line_item', 'credit_balance', 'payment_method',

package/src/utils/storage/helpers.ts

@@ -153,6 +153,66 @@ async function generateFileHash(file: File): Promise<string> {
   return `sha256:${hashHex}`;
 }
 
+/**
+ * Ensure a folder exists in the storage bucket
+ * In Supabase storage, folders are created automatically when files are uploaded,
+ * but this function explicitly creates the folder structure by uploading a placeholder
+ * file if the folder doesn't exist
+ * @param supabase - Supabase client instance
+ * @param folderPath - Folder path to ensure exists (e.g., 'orgId/folder')
+ * @param bucketName - Bucket name
+ * @returns True if folder exists or was created, false on error
+ */
+async function ensureFolderExists(
+  supabase: SupabaseClient,
+  folderPath: string,
+  bucketName: string
+): Promise<boolean> {
+  try {
+    // Check if folder exists by trying to list it
+    const { data, error } = await supabase.storage
+      .from(bucketName)
+      .list(folderPath, {
+        limit: 1
+      });
+
+    // If listing succeeds (even with empty data), the folder exists
+    if (!error) {
+      return true;
+    }
+
+    // If we get a "not found" error, the folder doesn't exist yet
+    // Create it by uploading a placeholder file
+    // Supabase storage doesn't support empty folders, so we create a .keep file
+    const placeholderPath = `${folderPath}/.keep`;
+    const placeholderBlob = new Blob([''], { type: 'text/plain' });
+    const placeholderFile = new File([placeholderBlob], '.keep', { type: 'text/plain' });
+
+    const { error: uploadError } = await supabase.storage
+      .from(bucketName)
+      .upload(placeholderPath, placeholderFile, {
+        cacheControl: '3600',
+        upsert: true, // Use upsert to avoid errors if file already exists
+        contentType: 'text/plain'
+      });
+
+    if (uploadError) {
+      // If we can't create the placeholder, log it but don't fail
+      // The folder will be created automatically when we upload the actual file
+      log.debug(`Could not create folder placeholder (will be created on upload): ${uploadError.message}`);
+      return true; // Still return true - folder will be created on actual file upload
+    }
+
+    // Folder structure now exists
+    return true;
+  } catch (error) {
+    // If there's an exception, log it but proceed anyway
+    // The folder structure will be created when we upload the actual file
+    log.debug(`Folder creation exception (will be created on upload): ${error instanceof Error ? error.message : 'Unknown error'}`);
+    return true; // Return true to proceed - folder will be created on actual file upload
+  }
+}
+
 /**
  * Upload a file to Supabase storage with app segregation
  */
@@ -175,13 +235,21 @@ export async function uploadFile(
     const uniqueFileName = generateUniqueFileName(file.name);
     const filePath = generateFilePath(options, uniqueFileName);
 
+    // Extract folder path from file path (everything except the filename)
+    const folderPath = filePath.substring(0, filePath.lastIndexOf('/'));
+
     // Extract metadata
     const metadata = await extractFileMetadata(file, options, 'current-user'); // TODO: Get actual user ID
 
     // Select bucket based on isPublic flag
     const bucketName = getBucketName(options.isPublic || false);
 
+    // Ensure folder exists (Supabase creates folders automatically on upload,
+    // but we verify the path is accessible)
+    await ensureFolderExists(supabase, folderPath, bucketName);
+
     // Upload file to Supabase
+    // Note: Supabase will automatically create the folder structure if it doesn't exist
     const { data, error } = await supabase.storage
       .from(bucketName)
       .upload(filePath, file, {

package/src/utils/timezone/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Timezone Utilities Exports
+ * @package @jmruthers/pace-core
+ * @module Utils/Timezone
+ * @since 0.1.0
+ */
+
+export {
+  formatInTimeZone,
+  getTimezoneAbbreviation,
+  formatTimeInTimeZone,
+  getUserTimeZone,
+  toZonedTime,
+  fromZonedTime,
+  roundToNearestMinutes,
+  getTimeZoneDifference
+} from './timezone';

package/src/utils/timezone/timezone.test.ts

@@ -0,0 +1,349 @@
+/**
+ * @file Timezone Utilities Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/Timezone/__tests__
+ * @since 0.1.0
+ *
+ * Comprehensive tests for timezone utility functions.
+ * Tests cover all major functionality, edge cases, and error handling.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  formatInTimeZone,
+  getTimezoneAbbreviation,
+  formatTimeInTimeZone,
+  getUserTimeZone,
+  toZonedTime,
+  fromZonedTime,
+  roundToNearestMinutes,
+  getTimeZoneDifference
+} from './timezone';
+
+describe('Timezone Utilities', () => {
+  describe('formatInTimeZone', () => {
+    it('formats a Date object in a specific timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatInTimeZone(date, 'America/New_York', 'MMM dd, yyyy HH:mm');
+      expect(result).toMatch(/Jan 15, 2024/);
+      expect(result).toMatch(/\d{2}:\d{2}/);
+    });
+
+    it('formats an ISO string in a specific timezone', () => {
+      const result = formatInTimeZone('2024-01-15T10:00:00Z', 'America/New_York', 'MMM dd, yyyy');
+      expect(result).toMatch(/Jan 15, 2024/);
+    });
+
+    it('formats a timestamp in a specific timezone', () => {
+      const timestamp = new Date('2024-01-15T10:00:00Z').getTime();
+      const result = formatInTimeZone(timestamp, 'America/New_York', 'yyyy-MM-dd');
+      expect(result).toBe('2024-01-15');
+    });
+
+    it('returns "Invalid date" for invalid date input', () => {
+      const result = formatInTimeZone(new Date('invalid'), 'America/New_York', 'MMM dd, yyyy');
+      expect(result).toBe('Invalid date');
+    });
+
+    it('returns "Invalid date" for invalid timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatInTimeZone(date, '', 'MMM dd, yyyy');
+      expect(result).toBe('Invalid date');
+    });
+
+    it('returns "Invalid date" for non-string timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      // @ts-expect-error - Testing invalid input
+      const result = formatInTimeZone(date, null, 'MMM dd, yyyy');
+      expect(result).toBe('Invalid date');
+    });
+
+    it('handles different timezones correctly', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const ny = formatInTimeZone(date, 'America/New_York', 'HH:mm');
+      const la = formatInTimeZone(date, 'America/Los_Angeles', 'HH:mm');
+      expect(ny).not.toBe(la);
+    });
+  });
+
+  describe('getTimezoneAbbreviation', () => {
+    it('returns timezone abbreviation for valid date and timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, 'America/New_York');
+      expect(typeof result).toBe('string');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('returns timezone name as fallback when abbreviation unavailable', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, 'America/New_York');
+      expect(result).toBeTruthy();
+    });
+
+    it('returns timezone string for invalid date', () => {
+      const result = getTimezoneAbbreviation(new Date('invalid'), 'America/New_York');
+      expect(result).toBe('America/New_York');
+    });
+
+    it('returns "UTC" for empty timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, '');
+      expect(result).toBe('UTC');
+    });
+
+    it('handles invalid timezone gracefully', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, 'Invalid/Timezone');
+      expect(typeof result).toBe('string');
+    });
+  });
+
+  describe('formatTimeInTimeZone', () => {
+    it('formats time only in specific timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatTimeInTimeZone(date, 'America/New_York');
+      expect(result).toMatch(/^\d{2}:\d{2}$/);
+    });
+
+    it('formats ISO string time in timezone', () => {
+      const result = formatTimeInTimeZone('2024-01-15T10:00:00Z', 'America/New_York');
+      expect(result).toMatch(/^\d{2}:\d{2}$/);
+    });
+
+    it('returns "Invalid date" for invalid input', () => {
+      const result = formatTimeInTimeZone(new Date('invalid'), 'America/New_York');
+      expect(result).toBe('Invalid date');
+    });
+  });
+
+  describe('getUserTimeZone', () => {
+    it('returns IANA timezone string', () => {
+      const result = getUserTimeZone();
+      expect(typeof result).toBe('string');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('returns "UTC" as fallback when Intl is unavailable', () => {
+      const originalIntl = global.Intl;
+      // @ts-expect-error - Testing fallback behavior
+      global.Intl = undefined;
+      const result = getUserTimeZone();
+      expect(result).toBe('UTC');
+      global.Intl = originalIntl;
+    });
+
+    it('returns "UTC" on error', () => {
+      const originalDateTimeFormat = Intl.DateTimeFormat;
+      // @ts-expect-error - Testing error handling
+      Intl.DateTimeFormat = () => {
+        throw new Error('Test error');
+      };
+      const result = getUserTimeZone();
+      expect(result).toBe('UTC');
+      Intl.DateTimeFormat = originalDateTimeFormat;
+    });
+  });
+
+  describe('toZonedTime', () => {
+    it('converts UTC date to timezone local time', () => {
+      const utcDate = new Date('2024-01-15T10:00:00Z');
+      const result = toZonedTime(utcDate, 'America/New_York');
+      expect(result).toBeInstanceOf(Date);
+      expect(result.getTime()).not.toBe(utcDate.getTime());
+    });
+
+    it('returns original date for invalid timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = toZonedTime(date, '');
+      expect(result).toBe(date);
+    });
+
+    it('returns original date for invalid date', () => {
+      const invalidDate = new Date('invalid');
+      const result = toZonedTime(invalidDate, 'America/New_York');
+      expect(result).toBe(invalidDate);
+    });
+
+    it('handles different timezones correctly', () => {
+      const utcDate = new Date('2024-01-15T10:00:00Z');
+      const ny = toZonedTime(utcDate, 'America/New_York');
+      const la = toZonedTime(utcDate, 'America/Los_Angeles');
+      expect(ny.getTime()).not.toBe(la.getTime());
+    });
+
+    it('returns original date on error', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      // @ts-expect-error - Testing error handling
+      const result = toZonedTime(date, null);
+      expect(result).toBe(date);
+    });
+  });
+
+  describe('fromZonedTime', () => {
+    it('converts local time in timezone to UTC', () => {
+      const localDate = new Date(2024, 0, 15, 10, 0); // Jan 15, 2024 10:00 AM local
+      const result = fromZonedTime(localDate, 'America/New_York');
+      expect(result).toBeInstanceOf(Date);
+    });
+
+    it('returns original date for invalid timezone', () => {
+      const date = new Date(2024, 0, 15, 10, 0);
+      const result = fromZonedTime(date, '');
+      expect(result).toBe(date);
+    });
+
+    it('returns original date for invalid date', () => {
+      const invalidDate = new Date('invalid');
+      const result = fromZonedTime(invalidDate, 'America/New_York');
+      expect(result).toBe(invalidDate);
+    });
+
+    it('handles round-trip conversion', () => {
+      const utcDate = new Date('2024-01-15T10:00:00Z');
+      const zoned = toZonedTime(utcDate, 'America/New_York');
+      const backToUtc = fromZonedTime(zoned, 'America/New_York');
+      // Should be close to original (within a few milliseconds due to DST handling)
+      expect(Math.abs(backToUtc.getTime() - utcDate.getTime())).toBeLessThan(1000);
+    });
+
+    it('returns original date on error', () => {
+      const date = new Date(2024, 0, 15, 10, 0);
+      // @ts-expect-error - Testing error handling
+      const result = fromZonedTime(date, null);
+      expect(result).toBe(date);
+    });
+  });
+
+  describe('roundToNearestMinutes', () => {
+    it('rounds to nearest 5 minutes by default', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date);
+      expect(result.getMinutes() % 5).toBe(0);
+    });
+
+    it('rounds to nearest specified minutes', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 10);
+      expect(result.getMinutes() % 10).toBe(0);
+    });
+
+    it('rounds up when closer to next interval', () => {
+      const date = new Date('2024-01-15T10:28:00Z');
+      const result = roundToNearestMinutes(date, 5);
+      expect(result.getMinutes()).toBe(30);
+    });
+
+    it('rounds down when closer to previous interval', () => {
+      const date = new Date('2024-01-15T10:22:00Z');
+      const result = roundToNearestMinutes(date, 5);
+      expect(result.getMinutes()).toBe(20);
+    });
+
+    it('returns original date for invalid date', () => {
+      const invalidDate = new Date('invalid');
+      const result = roundToNearestMinutes(invalidDate, 5);
+      expect(result).toBe(invalidDate);
+    });
+
+    it('returns original date for invalid minutesStep', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 0);
+      expect(date).toBe(date);
+    });
+
+    it('returns original date for negative minutesStep', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, -5);
+      expect(result).toBe(date);
+    });
+
+    it('returns original date for non-integer minutesStep', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 5.5);
+      expect(result).toBe(date);
+    });
+
+    it('handles edge case of exact minute', () => {
+      const date = new Date('2024-01-15T10:25:00Z');
+      const result = roundToNearestMinutes(date, 5);
+      expect(result.getMinutes()).toBe(25);
+    });
+  });
+
+  describe('getTimeZoneDifference', () => {
+    it('calculates difference between two timezones', () => {
+      const result = getTimeZoneDifference('America/New_York', 'America/Los_Angeles');
+      expect(typeof result).toBe('number');
+      // Los Angeles is typically 3 hours behind New York
+      expect(result).toBeLessThan(0);
+    });
+
+    it('returns 0 for same timezone', () => {
+      const result = getTimeZoneDifference('America/New_York', 'America/New_York');
+      expect(result).toBe(0);
+    });
+
+    it('returns 0 for invalid timezones', () => {
+      const result = getTimeZoneDifference('', 'America/New_York');
+      expect(result).toBe(0);
+    });
+
+    it('returns 0 for non-string timezones', () => {
+      // @ts-expect-error - Testing invalid input
+      const result = getTimeZoneDifference(null, 'America/New_York');
+      expect(result).toBe(0);
+    });
+
+    it('handles DST correctly', () => {
+      // Test in summer (EDT vs PDT = 3 hours)
+      const summerDate = new Date('2024-07-15T10:00:00Z');
+      const result = getTimeZoneDifference('America/New_York', 'America/Los_Angeles');
+      // Should be negative (LA behind NY)
+      expect(result).toBeLessThan(0);
+    });
+
+    it('returns 0 on error', () => {
+      // This test verifies error handling path
+      const result = getTimeZoneDifference('Invalid/Timezone1', 'Invalid/Timezone2');
+      expect(result).toBe(0);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles null and undefined inputs gracefully', () => {
+      // @ts-expect-error - Testing edge cases
+      expect(formatInTimeZone(null, 'America/New_York', 'yyyy-MM-dd')).toBe('Invalid date');
+      // @ts-expect-error - Testing edge cases
+      expect(formatInTimeZone(undefined, 'America/New_York', 'yyyy-MM-dd')).toBe('Invalid date');
+    });
+
+    it('handles extreme dates', () => {
+      const farFuture = new Date('2099-12-31T23:59:59Z');
+      const result = formatInTimeZone(farFuture, 'America/New_York', 'yyyy-MM-dd');
+      expect(result).toMatch(/2099-12-31/);
+
+      const farPast = new Date('1900-01-01T00:00:00Z');
+      const result2 = formatInTimeZone(farPast, 'America/New_York', 'yyyy-MM-dd');
+      // Timezone conversion may shift the date to previous day due to timezone offset
+      // Accept either 1900-01-01 or 1899-12-31 depending on timezone offset
+      expect(result2).toMatch(/1899-12-31|1900-01-01/);
+    });
+
+    it('handles various timezone formats', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const timezones = [
+        'America/New_York',
+        'Europe/London',
+        'Asia/Tokyo',
+        'Australia/Sydney',
+        'UTC'
+      ];
+
+      timezones.forEach(tz => {
+        const result = formatInTimeZone(date, tz, 'yyyy-MM-dd');
+        expect(result).toBe('2024-01-15');
+      });
+    });
+  });
+});
+