@tuturuuu/utils 0.0.3 → 0.6.0

package/src/app-url.ts

@@ -0,0 +1,96 @@
+import { type AppName, getAppDomainByUrl } from './internal-domains';
+
+type AppUrlCandidate = string | null | undefined;
+
+interface ResolveAppUrlOptions {
+  candidates: readonly AppUrlCandidate[];
+  fallback: string;
+}
+
+interface ResolveInternalAppUrlOptions extends ResolveAppUrlOptions {
+  appName: AppName;
+}
+
+function trimTrailingSlashes(value: string) {
+  let end = value.length;
+
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+
+  return end === value.length ? value : value.slice(0, end);
+}
+
+function isWildcardListenerHostname(hostname: string) {
+  return hostname === '0.0.0.0' || hostname === '::' || hostname === '[::]';
+}
+
+function normalizeHttpUrl(value: AppUrlCandidate) {
+  const trimmed = value?.trim();
+
+  if (!trimmed) {
+    return null;
+  }
+
+  try {
+    const url = new URL(trimmed);
+
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return null;
+    }
+
+    if (isWildcardListenerHostname(url.hostname)) {
+      return null;
+    }
+
+    return trimTrailingSlashes(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+export function resolveAppUrl({ candidates, fallback }: ResolveAppUrlOptions) {
+  for (const candidate of candidates) {
+    const resolvedUrl = normalizeHttpUrl(candidate);
+
+    if (resolvedUrl) {
+      return resolvedUrl;
+    }
+  }
+
+  return normalizeHttpUrl(fallback) ?? fallback;
+}
+
+function getRegisteredAppNameForUrl(value: string) {
+  return getAppDomainByUrl(value)?.name ?? null;
+}
+
+export function resolveInternalAppUrl({
+  appName,
+  candidates,
+  fallback,
+}: ResolveInternalAppUrlOptions) {
+  for (const candidate of candidates) {
+    const resolvedUrl = normalizeHttpUrl(candidate);
+
+    if (!resolvedUrl) {
+      continue;
+    }
+
+    const registeredAppName = getRegisteredAppNameForUrl(resolvedUrl);
+
+    if (registeredAppName && registeredAppName !== appName) {
+      continue;
+    }
+
+    const registeredAppUrl = getAppDomainByUrl(resolvedUrl);
+
+    if (registeredAppUrl?.kind === 'internal') {
+      return trimTrailingSlashes(registeredAppUrl.canonicalUrl);
+    }
+
+    return resolvedUrl;
+  }
+
+  return normalizeHttpUrl(fallback) ?? fallback;
+}

package/src/avatar-url.ts

@@ -0,0 +1,64 @@
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SUPABASE_PUBLIC_AVATAR_PATH = '/storage/v1/object/public/avatars/';
+const SUPABASE_MALFORMED_PUBLIC_AVATAR_PATH =
+  '/storage/v1/object/v1/public/avatars/';
+
+function getSupabasePublicAvatarObjectPath(pathname: string) {
+  if (pathname.startsWith(SUPABASE_PUBLIC_AVATAR_PATH)) {
+    return pathname.slice(SUPABASE_PUBLIC_AVATAR_PATH.length);
+  }
+
+  if (pathname.startsWith(SUPABASE_MALFORMED_PUBLIC_AVATAR_PATH)) {
+    return pathname.slice(SUPABASE_MALFORMED_PUBLIC_AVATAR_PATH.length);
+  }
+
+  return null;
+}
+
+function normalizeSupabasePublicAvatarUrl(src: string) {
+  try {
+    const sourceUrl = new URL(src);
+    const avatarObjectPath = getSupabasePublicAvatarObjectPath(
+      sourceUrl.pathname
+    );
+
+    if (
+      !sourceUrl.hostname.endsWith('.supabase.co') ||
+      avatarObjectPath === null
+    ) {
+      return src;
+    }
+
+    sourceUrl.pathname = `${SUPABASE_PUBLIC_AVATAR_PATH}${avatarObjectPath}`;
+
+    return sourceUrl.toString();
+  } catch {
+    return src;
+  }
+}
+
+export function normalizeAvatarImageSrc(
+  value: string | null | undefined
+): string | undefined {
+  const src = value?.trim();
+
+  if (!src || src.startsWith('//') || UUID_PATTERN.test(src)) {
+    return undefined;
+  }
+
+  if (/^https?:\/\//iu.test(src)) {
+    return normalizeSupabasePublicAvatarUrl(src);
+  }
+
+  if (
+    src.startsWith('/') ||
+    src.startsWith('blob:') ||
+    /^data:image\//iu.test(src) ||
+    src.startsWith('avatars/')
+  ) {
+    return src;
+  }
+
+  return undefined;
+}

package/src/break-duration.ts

@@ -0,0 +1,84 @@
+/**
+ * Break Duration Utilities
+ *
+ * Handles validation and formatting for break durations.
+ * Breaks are constrained to multiples of 15 minutes.
+ */
+
+/** The interval in minutes that break durations must be multiples of */
+export const BREAK_INTERVAL = 15;
+
+/** Minimum break duration in minutes */
+export const MIN_BREAK_MINUTES = 15;
+
+/** Maximum break duration in minutes (2 hours) */
+export const MAX_BREAK_MINUTES = 120;
+
+/** Available break duration options in minutes */
+export const BREAK_OPTIONS = [15, 30, 45, 60, 75, 90, 105, 120] as const;
+
+/** Type for valid break duration values */
+export type BreakDuration = (typeof BREAK_OPTIONS)[number];
+
+/**
+ * Check if a duration value is a valid break duration
+ * (positive, multiple of 15, within bounds)
+ */
+export function isValidBreakDuration(minutes: number): boolean {
+  return (
+    minutes > 0 &&
+    minutes % BREAK_INTERVAL === 0 &&
+    minutes >= MIN_BREAK_MINUTES &&
+    minutes <= MAX_BREAK_MINUTES
+  );
+}
+
+/**
+ * Round a duration to the nearest valid break interval
+ */
+export function roundToBreakInterval(minutes: number): number {
+  const rounded = Math.round(minutes / BREAK_INTERVAL) * BREAK_INTERVAL;
+  return Math.max(MIN_BREAK_MINUTES, Math.min(MAX_BREAK_MINUTES, rounded));
+}
+
+/**
+ * Format a break duration for display
+ * @param minutes Duration in minutes
+ * @returns Formatted string (e.g., "15 min", "1h", "1h 30m")
+ */
+export function formatBreakDuration(minutes: number): string {
+  if (minutes < 60) {
+    return `${minutes} min`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const mins = minutes % 60;
+  if (mins === 0) {
+    return `${hours}h`;
+  }
+  return `${hours}h ${mins}m`;
+}
+
+/**
+ * Get break options as label-value pairs for use in select components
+ */
+export function getBreakOptionLabels(): Array<{
+  value: number;
+  label: string;
+}> {
+  return BREAK_OPTIONS.map((mins) => ({
+    value: mins,
+    label: formatBreakDuration(mins),
+  }));
+}
+
+/**
+ * Parse a break duration from input, ensuring it's valid
+ * Returns null if invalid
+ */
+export function parseBreakDuration(value: unknown): number | null {
+  const num = typeof value === 'string' ? parseInt(value, 10) : Number(value);
+  if (Number.isNaN(num) || !isValidBreakDuration(num)) {
+    return null;
+  }
+  return num;
+}

package/src/calendar-auth-token.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  fetchUserWorkspaceCalendarGoogleTokenForClient,
+  WORKSPACE_CALENDAR_GOOGLE_TOKEN_CLIENT_SELECT,
+} from './calendar-auth-token';
+
+describe('calendar-auth-token', () => {
+  it('does not request OAuth secret columns', () => {
+    expect(WORKSPACE_CALENDAR_GOOGLE_TOKEN_CLIENT_SELECT).not.toContain(
+      'access_token'
+    );
+    expect(WORKSPACE_CALENDAR_GOOGLE_TOKEN_CLIENT_SELECT).not.toContain(
+      'refresh_token'
+    );
+  });
+
+  it('scopes token reads to workspace and authenticated user', async () => {
+    const maybeSingle = vi.fn().mockResolvedValue({ data: null, error: null });
+    const eqUser = vi.fn().mockReturnValue({ maybeSingle });
+    const eqWorkspace = vi.fn().mockReturnValue({ eq: eqUser });
+    const select = vi.fn().mockReturnValue({ eq: eqWorkspace });
+    const from = vi.fn().mockReturnValue({ select });
+
+    await fetchUserWorkspaceCalendarGoogleTokenForClient({ from } as never, {
+      wsId: 'ws-1',
+      userId: 'user-1',
+    });
+
+    expect(from).toHaveBeenCalledWith('calendar_auth_tokens');
+    expect(select).toHaveBeenCalledWith(
+      WORKSPACE_CALENDAR_GOOGLE_TOKEN_CLIENT_SELECT
+    );
+    expect(eqWorkspace).toHaveBeenCalledWith('ws_id', 'ws-1');
+    expect(eqUser).toHaveBeenCalledWith('user_id', 'user-1');
+    expect(maybeSingle).toHaveBeenCalledOnce();
+  });
+});

package/src/calendar-auth-token.ts

@@ -0,0 +1,19 @@
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import type { WorkspaceCalendarGoogleTokenClient } from '@tuturuuu/types/db';
+
+export const WORKSPACE_CALENDAR_GOOGLE_TOKEN_CLIENT_SELECT =
+  'id, ws_id, user_id, provider, account_email, account_name, is_active, expires_at, created_at' as const;
+
+export async function fetchUserWorkspaceCalendarGoogleTokenForClient(
+  supabase: TypedSupabaseClient,
+  params: { wsId: string; userId: string }
+): Promise<WorkspaceCalendarGoogleTokenClient | null> {
+  const { data } = await supabase
+    .from('calendar_auth_tokens')
+    .select(WORKSPACE_CALENDAR_GOOGLE_TOKEN_CLIENT_SELECT)
+    .eq('ws_id', params.wsId)
+    .eq('user_id', params.userId)
+    .maybeSingle();
+
+  return data;
+}

package/src/calendar-sync-coordination.md

@@ -0,0 +1,197 @@
+# Calendar Sync Coordination
+
+This module provides utilities to coordinate calendar sync operations between active sync (user-initiated) and background sync (automated) to prevent conflicts and ensure data consistency.
+
+## Overview
+
+The calendar sync coordination system uses a `lastUpsert` timestamp to enforce a 30-second cooldown period between sync operations for each workspace. Additionally, it includes a 4-week range check to ensure syncs only operate within a reasonable time window from the current week. This prevents:
+
+- Race conditions between active and background syncs
+- Excessive API calls to Google Calendar
+- Data inconsistencies from concurrent updates
+- Syncs on date ranges too far in the past or future
+
+## Database Schema
+
+The system uses a `workspace_calendar_sync_coordination` table:
+
+```sql
+CREATE TABLE workspace_calendar_sync_coordination (
+    ws_id UUID PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+    last_upsert TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+```
+
+## Functions
+
+### `canProceedWithSync(wsId: string, supabase?: any): Promise<boolean>`
+
+Checks if a sync operation can proceed for the given workspace.
+
+**Parameters:**
+
+- `wsId`: The workspace ID
+- `supabase`: Optional Supabase client (will create one if not provided)
+
+**Returns:**
+
+- `true` if sync can proceed (30+ seconds since last upsert)
+- `false` if sync is blocked (less than 30 seconds since last upsert)
+
+**Behavior:**
+
+- Creates a coordination record if one doesn't exist for the workspace
+- Allows sync for new workspaces (no existing record)
+- Gracefully handles errors by allowing sync to proceed
+
+### `isWithin4WeeksFromCurrentWeek(startDate: Date, endDate: Date): boolean`
+
+Checks if a date range is within 4 weeks from the current week.
+
+**Parameters:**
+
+- `startDate`: Start date to check
+- `endDate`: End date to check
+
+**Returns:**
+
+- `true` if the date range overlaps with 4 weeks from current week
+- `false` if the date range is outside the 4-week window
+
+**Behavior:**
+
+- Uses the current week as the reference point (not the current view)
+- Checks if the date range overlaps with the 4-week period
+- Useful for preventing syncs on distant past or future dates
+
+### `updateLastUpsert(wsId: string, supabase?: any): Promise<void>`
+
+Updates the `last_upsert` timestamp for a workspace after a successful sync operation.
+
+**Parameters:**
+
+- `wsId`: The workspace ID
+- `supabase`: Optional Supabase client (will create one if not provided)
+
+**Behavior:**
+
+- Upserts the timestamp using the workspace ID as the conflict target
+- Logs success or error messages
+- Gracefully handles errors
+
+### `FOUR_WEEKS_FROM_CURRENT_WEEK`
+
+Constant representing 4 weeks (28 days) from the current week.
+
+## Usage
+
+### Active Sync (use-calendar-sync.tsx)
+
+```typescript
+import {
+  canProceedWithSync,
+  isWithin4WeeksFromCurrentWeek,
+  updateLastUpsert,
+} from '@tuturuuu/utils/calendar-sync-coordination';
+
+const syncToTuturuuu = async () => {
+  // Check if current view is within 4 weeks from current week
+  if (dates.length > 0) {
+    const startDate = dates[0];
+    const endDate = dates[dates.length - 1];
+
+    if (startDate && endDate) {
+      const isWithinRange = isWithin4WeeksFromCurrentWeek(startDate, endDate);
+
+      if (!isWithinRange) {
+        console.log(
+          'Sync blocked: Current view is outside 4 weeks from current week'
+        );
+        return;
+      }
+    }
+  }
+
+  // Check if we can proceed with sync
+  const canProceed = await canProceedWithSync(wsId);
+  if (!canProceed) {
+    console.log('Sync blocked due to 30-second cooldown');
+    return;
+  }
+
+  // Perform sync operations...
+
+  // Update timestamp after successful upsert
+  await updateLastUpsert(wsId);
+};
+```
+
+### Background Sync (google-calendar-background-sync.ts)
+
+```typescript
+import {
+  FOUR_WEEKS_FROM_CURRENT_WEEK,
+  canProceedWithSync,
+  updateLastUpsert,
+} from '@tuturuuu/utils/calendar-sync-coordination';
+
+const syncGoogleCalendarEvents = async (supabase: any) => {
+  for (const token of tokens) {
+    // Check if we can proceed with sync for this workspace
+    const canProceed = await canProceedWithSync(token.ws_id, supabase);
+    if (!canProceed) {
+      console.log(
+        `Skipping background sync for wsId ${token.ws_id} due to 30-second cooldown`
+      );
+      continue;
+    }
+
+    // Perform sync operations with 4-week range
+    const timeMin = new Date();
+    const timeMax = new Date();
+    timeMax.setDate(timeMax.getDate() + FOUR_WEEKS_FROM_CURRENT_WEEK);
+
+    // ... sync logic ...
+
+    // Update timestamp after successful upsert
+    await updateLastUpsert(token.ws_id, supabase);
+  }
+};
+```
+
+## Error Handling
+
+All functions are designed to be fault-tolerant:
+
+- If the coordination table doesn't exist, sync operations are allowed to proceed
+- If database operations fail, sync operations are allowed to proceed
+- All errors are logged but don't block sync operations
+- This ensures the system degrades gracefully if the coordination mechanism fails
+
+## Migration
+
+To set up the coordination table, run the migration:
+
+```sql
+-- Create table to coordinate calendar sync operations
+CREATE TABLE workspace_calendar_sync_coordination (
+    ws_id UUID PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+    last_upsert TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Add RLS policies and triggers as needed
+```
+
+## Benefits
+
+1. **Prevents Conflicts**: Ensures only one sync operation per workspace every 30 seconds
+2. **Reduces API Load**: Prevents excessive calls to Google Calendar API
+3. **Maintains Consistency**: Avoids race conditions that could corrupt data
+4. **Graceful Degradation**: System continues to work even if coordination fails
+5. **Workspace Isolation**: Each workspace has its own coordination record
+6. **Reasonable Time Window**: Prevents syncs on distant past or future dates
+7. **Current Week Reference**: Uses current week as reference point for 4-week window

package/src/calendar-utils.test.ts

@@ -0,0 +1,169 @@
+import type { CalendarEvent } from '@tuturuuu/types/primitives/calendar-event';
+import { describe, expect, it } from 'vitest';
+import {
+  convertGoogleAllDayEvent,
+  createAllDayEvent,
+  isAllDayEvent,
+} from './calendar-utils';
+
+describe('calendar-utils', () => {
+  describe('isAllDayEvent', () => {
+    it('should detect all-day events with date-only format', () => {
+      const event: Pick<CalendarEvent, 'start_at' | 'end_at'> = {
+        start_at: '2024-01-01T00:00:00.000Z',
+        end_at: '2024-01-02T00:00:00.000Z',
+      };
+
+      expect(isAllDayEvent(event)).toBe(true);
+    });
+
+    it('should detect all-day events spanning multiple days', () => {
+      const event: Pick<CalendarEvent, 'start_at' | 'end_at'> = {
+        start_at: '2024-01-01T00:00:00.000Z',
+        end_at: '2024-01-03T00:00:00.000Z', // 48 hours
+      };
+
+      expect(isAllDayEvent(event)).toBe(true);
+    });
+
+    it('should reject timed events', () => {
+      const event: Pick<CalendarEvent, 'start_at' | 'end_at'> = {
+        start_at: '2024-01-01T10:00:00.000Z',
+        end_at: '2024-01-01T11:00:00.000Z',
+      };
+
+      expect(isAllDayEvent(event)).toBe(false);
+    });
+
+    it('should reject events not starting at midnight', () => {
+      const event: Pick<CalendarEvent, 'start_at' | 'end_at'> = {
+        start_at: '2024-01-01T01:00:00.000Z',
+        end_at: '2024-01-02T00:00:00.000Z',
+      };
+
+      expect(isAllDayEvent(event)).toBe(false);
+    });
+
+    it('should reject events not ending at midnight', () => {
+      const event: Pick<CalendarEvent, 'start_at' | 'end_at'> = {
+        start_at: '2024-01-01T00:00:00.000Z',
+        end_at: '2024-01-02T01:00:00.000Z',
+      };
+
+      expect(isAllDayEvent(event)).toBe(false);
+    });
+
+    it('should reject events with non-24-hour duration', () => {
+      const event: Pick<CalendarEvent, 'start_at' | 'end_at'> = {
+        start_at: '2024-01-01T00:00:00.000Z',
+        end_at: '2024-01-01T12:00:00.000Z', // 12 hours
+      };
+
+      expect(isAllDayEvent(event)).toBe(false);
+    });
+
+    it('should reject events with 0 duration', () => {
+      const event: Pick<CalendarEvent, 'start_at' | 'end_at'> = {
+        start_at: '2024-01-01T00:00:00.000Z',
+        end_at: '2024-01-01T00:00:00.000Z', // Same time
+      };
+
+      expect(isAllDayEvent(event)).toBe(false);
+    });
+
+    it('should handle events with seconds and milliseconds', () => {
+      const event: Pick<CalendarEvent, 'start_at' | 'end_at'> = {
+        start_at: '2024-01-01T00:00:00.123Z',
+        end_at: '2024-01-02T00:00:00.456Z',
+      };
+
+      expect(isAllDayEvent(event)).toBe(false);
+    });
+  });
+
+  describe('convertGoogleAllDayEvent', () => {
+    it('should convert Google date-only format to user timezone midnight', () => {
+      const result = convertGoogleAllDayEvent(
+        '2024-01-01',
+        '2024-01-02',
+        'America/New_York'
+      );
+
+      // Should convert to timezone midnight
+      expect(result.start_at).toMatch(/2024-01-01T05:00:00\.000Z/); // UTC equivalent of midnight EST
+      expect(result.end_at).toMatch(/2024-01-02T05:00:00\.000Z/);
+    });
+
+    it('should handle missing dates by using current time', () => {
+      const result = convertGoogleAllDayEvent(
+        undefined,
+        undefined,
+        'America/New_York'
+      );
+
+      expect(result.start_at).toBeDefined();
+      expect(result.end_at).toBeDefined();
+      expect(
+        new Date(result.end_at).getTime() - new Date(result.start_at).getTime()
+      ).toBe(60 * 60 * 1000); // 1 hour
+    });
+
+    it('should pass through existing dateTime format unchanged', () => {
+      const result = convertGoogleAllDayEvent(
+        '2024-01-01T10:00:00Z',
+        '2024-01-01T11:00:00Z',
+        'America/New_York'
+      );
+
+      expect(result.start_at).toBe('2024-01-01T10:00:00Z');
+      expect(result.end_at).toBe('2024-01-01T11:00:00Z');
+    });
+
+    it('should handle mixed date formats', () => {
+      const result = convertGoogleAllDayEvent(
+        '2024-01-01',
+        '2024-01-01T11:00:00Z',
+        'America/New_York'
+      );
+
+      // Should pass through as-is since not both are date-only
+      expect(result.start_at).toBe('2024-01-01');
+      expect(result.end_at).toBe('2024-01-01T11:00:00Z');
+    });
+  });
+
+  describe('createAllDayEvent', () => {
+    it('should create all-day event in user timezone', () => {
+      const date = new Date('2024-01-01T10:00:00Z');
+      const result = createAllDayEvent(date, 'America/New_York');
+
+      expect(result.start_at).toMatch(/2024-01-01T05:00:00\.000Z/); // UTC equivalent of midnight EST
+      expect(result.end_at).toMatch(/2024-01-02T05:00:00\.000Z/);
+    });
+
+    it('should create multi-day all-day event', () => {
+      const date = new Date('2024-01-01T10:00:00Z');
+      const result = createAllDayEvent(date, 'America/New_York', 3);
+
+      expect(result.start_at).toMatch(/2024-01-01T05:00:00\.000Z/);
+      expect(result.end_at).toMatch(/2024-01-04T05:00:00\.000Z/); // 3 days later
+    });
+
+    it('should handle undefined timezone', () => {
+      const date = new Date('2024-01-01T10:00:00Z');
+      const result = createAllDayEvent(date, undefined);
+
+      // When timezone is undefined, the function should use the system's local timezone.
+      // To make this test robust regardless of the environment, we compute the expected UTC start/end.
+      const localDate = new Date(date);
+      localDate.setHours(0, 0, 0, 0);
+      const expectedStart = localDate.toISOString();
+      const expectedEnd = new Date(
+        localDate.getTime() + 24 * 60 * 60 * 1000
+      ).toISOString();
+
+      expect(result.start_at).toBe(expectedStart);
+      expect(result.end_at).toBe(expectedEnd);
+    });
+  });
+});