@tuturuuu/ai 0.0.10

package/src/tools/executors/timer/timer-mutation-schemas.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+
+const dateOnlyStringSchema = z
+  .string()
+  .trim()
+  .regex(/^\d{4}-\d{2}-\d{2}$/, 'date must use YYYY-MM-DD format');
+
+const flexibleDateTimeStringSchema = z
+  .string()
+  .trim()
+  .regex(
+    /^(?:\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,3})?)?(?:Z|[+-][01]\d:[0-5]\d)?|\d{4}-\d{2}-\d{2}\s+(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?|(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?)$/,
+    'must be a valid ISO datetime, YYYY-MM-DD HH:mm, or HH:mm/HH:mm:ss'
+  );
+
+const temporalDateTimeInputSchema = z.union([
+  z.date(),
+  flexibleDateTimeStringSchema,
+]);
+const temporalDateInputSchema = z.union([z.date(), dateOnlyStringSchema]);
+
+export const startTimerArgsSchema = z.object({
+  title: z.string().trim().min(1, 'title is required'),
+  description: z.union([z.string(), z.null()]).optional(),
+});
+
+export type StartTimerArgs = z.infer<typeof startTimerArgsSchema>;
+
+export const stopTimerArgsSchema = z.object({
+  sessionId: z.union([z.string(), z.null()]).optional(),
+});
+
+export type StopTimerArgs = z.infer<typeof stopTimerArgsSchema>;
+
+export const createTimeTrackingEntryArgsSchema = z.object({
+  title: z.string().trim().min(1, 'title is required'),
+  description: z.union([z.string(), z.null()]).optional(),
+  categoryId: z.union([z.string(), z.null()]).optional(),
+  taskId: z.union([z.string(), z.null()]).optional(),
+  startTime: temporalDateTimeInputSchema,
+  endTime: temporalDateTimeInputSchema,
+  date: temporalDateInputSchema.optional(),
+});
+
+export type CreateTimeTrackingEntryArgs = z.infer<
+  typeof createTimeTrackingEntryArgsSchema
+>;
+
+export const updateTimeTrackingSessionArgsSchema = z.object({
+  sessionId: z.union([z.string(), z.null()]).optional(),
+  id: z.union([z.string(), z.null()]).optional(),
+  title: z.union([z.string(), z.null()]).optional(),
+  description: z.union([z.string(), z.null()]).optional(),
+  categoryId: z.union([z.string(), z.null()]).optional(),
+  taskId: z.union([z.string(), z.null()]).optional(),
+  startTime: temporalDateTimeInputSchema.optional(),
+  endTime: temporalDateTimeInputSchema.optional(),
+  date: temporalDateInputSchema.optional(),
+});
+
+export type UpdateTimeTrackingSessionArgs = z.infer<
+  typeof updateTimeTrackingSessionArgsSchema
+>;
+
+export const deleteTimeTrackingSessionArgsSchema = z.object({
+  sessionId: z.union([z.string(), z.null()]).optional(),
+  id: z.union([z.string(), z.null()]).optional(),
+});
+
+export type DeleteTimeTrackingSessionArgs = z.infer<
+  typeof deleteTimeTrackingSessionArgsSchema
+>;
+
+export const moveTimeTrackingSessionArgsSchema = z.object({
+  sessionId: z.union([z.string(), z.null()]).optional(),
+  id: z.union([z.string(), z.null()]).optional(),
+  targetWorkspaceId: z.string().trim().min(1, 'targetWorkspaceId is required'),
+});
+
+export type MoveTimeTrackingSessionArgs = z.infer<
+  typeof moveTimeTrackingSessionArgsSchema
+>;
+
+export const createTimeTrackerGoalArgsSchema = z.object({
+  categoryId: z.union([z.string(), z.null()]).optional(),
+  dailyGoalMinutes: z
+    .number()
+    .int()
+    .min(1, 'dailyGoalMinutes must be greater than 0'),
+  weeklyGoalMinutes: z.union([z.number().int().min(1), z.null()]).optional(),
+  isActive: z.boolean().optional(),
+});
+
+export type CreateTimeTrackerGoalArgs = z.infer<
+  typeof createTimeTrackerGoalArgsSchema
+>;
+
+export const updateTimeTrackerGoalArgsSchema = z.object({
+  goalId: z.union([z.string(), z.null()]).optional(),
+  id: z.union([z.string(), z.null()]).optional(),
+  categoryId: z.union([z.string(), z.null()]).optional(),
+  dailyGoalMinutes: z
+    .number()
+    .int()
+    .min(1, 'dailyGoalMinutes must be greater than 0')
+    .optional(),
+  weeklyGoalMinutes: z.union([z.number().int().min(1), z.null()]).optional(),
+  isActive: z.boolean().optional(),
+});
+
+export type UpdateTimeTrackerGoalArgs = z.infer<
+  typeof updateTimeTrackerGoalArgsSchema
+>;
+
+export const deleteTimeTrackerGoalArgsSchema = z.object({
+  goalId: z.union([z.string(), z.null()]).optional(),
+  id: z.union([z.string(), z.null()]).optional(),
+});
+
+export type DeleteTimeTrackerGoalArgs = z.infer<
+  typeof deleteTimeTrackerGoalArgsSchema
+>;
+
+export const createTimeTrackingCategoryArgsSchema = z.object({
+  name: z.string().trim().min(1, 'name is required'),
+  description: z.union([z.string(), z.null()]).optional(),
+  color: z.union([z.string(), z.null()]).optional(),
+});
+
+export type CreateTimeTrackingCategoryArgs = z.infer<
+  typeof createTimeTrackingCategoryArgsSchema
+>;
+
+export const updateTimeTrackingCategoryArgsSchema = z.object({
+  categoryId: z.union([z.string(), z.null()]).optional(),
+  id: z.union([z.string(), z.null()]).optional(),
+  name: z.union([z.string(), z.null()]).optional(),
+  description: z.union([z.string(), z.null()]).optional(),
+  color: z.union([z.string(), z.null()]).optional(),
+});
+
+export type UpdateTimeTrackingCategoryArgs = z.infer<
+  typeof updateTimeTrackingCategoryArgsSchema
+>;
+
+export const deleteTimeTrackingCategoryArgsSchema = z.object({
+  categoryId: z.union([z.string(), z.null()]).optional(),
+  id: z.union([z.string(), z.null()]).optional(),
+});
+
+export type DeleteTimeTrackingCategoryArgs = z.infer<
+  typeof deleteTimeTrackingCategoryArgsSchema
+>;
+
+export function getZodErrorMessage(error: unknown): string {
+  if (error instanceof z.ZodError) {
+    return error.issues[0]?.message ?? 'Invalid arguments';
+  }
+  return 'Invalid arguments';
+}

package/src/tools/executors/timer/timer-mutation-types.ts

@@ -0,0 +1,212 @@
+import type { Tables } from '@tuturuuu/types';
+
+export type MutationError = { error: string };
+
+export type TimerRelatedEntity = {
+  id: string;
+  name: string | null;
+  color: string | null;
+} | null;
+
+export type TimeTrackingCategory = Tables<'time_tracking_categories'>;
+
+export interface TimerSession {
+  id: string;
+  title: string | null;
+  startedAt: string | number;
+  endedAt?: string | number | null;
+  pausedAt?: string | number | null;
+  elapsedMs?: number;
+  durationSeconds?: number | null;
+  durationFormatted?: string;
+  description?: string | null;
+  categoryId?: string | null;
+  taskId?: string | null;
+  isRunning?: boolean;
+  pendingApproval?: boolean;
+  wsId?: string;
+  category?: TimerRelatedEntity;
+  task?: TimerRelatedEntity;
+}
+
+function asTimerRelatedEntity(value: unknown): TimerRelatedEntity {
+  if (!value || typeof value !== 'object') return null;
+
+  const candidate = value as Record<string, unknown>;
+  const id = typeof candidate.id === 'string' ? candidate.id : null;
+  if (!id) return null;
+
+  const name =
+    typeof candidate.name === 'string' || candidate.name === null
+      ? candidate.name
+      : null;
+  const color =
+    typeof candidate.color === 'string' || candidate.color === null
+      ? candidate.color
+      : null;
+
+  return {
+    id,
+    name,
+    color,
+  };
+}
+
+export function toTimerSession(
+  row: Record<string, unknown>,
+  overrides: Partial<TimerSession> = {}
+): TimerSession {
+  const sessionId =
+    typeof row.id === 'string' && row.id.trim().length > 0 ? row.id : null;
+  if (!sessionId) {
+    throw new Error('Invalid or missing session id');
+  }
+
+  const startedAt =
+    typeof row.start_time === 'string' || typeof row.start_time === 'number'
+      ? row.start_time
+      : typeof row.created_at === 'string' || typeof row.created_at === 'number'
+        ? row.created_at
+        : typeof row.updated_at === 'string' ||
+            typeof row.updated_at === 'number'
+          ? row.updated_at
+          : new Date(0).toISOString();
+
+  const baseSession: TimerSession = {
+    id: sessionId,
+    title: typeof row.title === 'string' ? row.title : null,
+    startedAt,
+    endedAt:
+      typeof row.end_time === 'string' || typeof row.end_time === 'number'
+        ? row.end_time
+        : null,
+    durationSeconds:
+      typeof row.duration_seconds === 'number' ? row.duration_seconds : null,
+    description: typeof row.description === 'string' ? row.description : null,
+    categoryId: typeof row.category_id === 'string' ? row.category_id : null,
+    taskId: typeof row.task_id === 'string' ? row.task_id : null,
+    isRunning: typeof row.is_running === 'boolean' ? row.is_running : undefined,
+    pendingApproval:
+      typeof row.pending_approval === 'boolean'
+        ? row.pending_approval
+        : undefined,
+    wsId: typeof row.ws_id === 'string' ? row.ws_id : undefined,
+    category: asTimerRelatedEntity(row.category),
+    task: asTimerRelatedEntity(row.task),
+  };
+
+  return { ...baseSession, ...overrides };
+}
+
+export type StartTimerResult =
+  | MutationError
+  | {
+      success: true;
+      message: string;
+      session: TimerSession;
+    };
+
+export type StopTimerResult =
+  | MutationError
+  | {
+      success: true;
+      message: string;
+      session: TimerSession;
+    };
+
+export type CreateTimeTrackingEntryResult =
+  | MutationError
+  | {
+      success: true;
+      requiresApproval: false;
+      message: string;
+      session: TimerSession;
+    }
+  | {
+      success: true;
+      requiresApproval: true;
+      requestCreated: boolean;
+      message?: string;
+      nextStep?: string;
+      approvalRequest?: {
+        startTime: string;
+        endTime: string;
+        titleHint: string;
+        descriptionHint: string | null;
+      };
+    };
+
+export type UpdateTimeTrackingSessionResult =
+  | MutationError
+  | {
+      success: true;
+      message: string;
+      session?: TimerSession;
+    };
+
+export type DeleteTimeTrackingSessionResult =
+  | MutationError
+  | {
+      success: true;
+      message: string;
+    };
+
+export type MoveTimeTrackingSessionResult =
+  | MutationError
+  | {
+      success: true;
+      message: string;
+      session: TimerSession;
+    };
+
+export type TimerGoal = {
+  id: string;
+  ws_id: string;
+  user_id: string;
+  category_id: string | null;
+  daily_goal_minutes: number;
+  weekly_goal_minutes: number | null;
+  is_active: boolean | null;
+  created_at: string;
+  updated_at: string;
+  category:
+    | {
+        id: string;
+        name: string | null;
+        color: string | null;
+      }
+    | Array<{
+        id: string;
+        name: string | null;
+        color: string | null;
+      }>
+    | null;
+};
+
+export function normalizeGoalCategory(category: TimerGoal['category']) {
+  if (!category) return null;
+  if (Array.isArray(category)) return category[0] ?? null;
+  return category;
+}
+
+export function normalizeGoalCategoryIdInput(
+  value: unknown
+): { ok: true; categoryId: string | null } | { ok: false; error: string } {
+  if (value === undefined || value === null) {
+    return { ok: true, categoryId: null };
+  }
+
+  if (typeof value !== 'string') {
+    return { ok: false, error: 'categoryId must be a string or null' };
+  }
+
+  const trimmed = value.trim();
+  // User-facing normalization: treat blank and "general" category inputs as
+  // the same "no category" intent, so the trimmed value reaches the branch
+  // below that returns { ok: true, categoryId: null }.
+  if (!trimmed || trimmed.toLowerCase() === 'general') {
+    return { ok: true, categoryId: null };
+  }
+
+  return { ok: true, categoryId: trimmed };
+}

package/src/tools/executors/timer/timer-mutations.ts

@@ -0,0 +1,19 @@
+export {
+  executeCreateTimeTrackingCategory,
+  executeDeleteTimeTrackingCategory,
+  executeUpdateTimeTrackingCategory,
+} from './timer-category-mutations';
+export {
+  executeCreateTimeTrackerGoal,
+  executeDeleteTimeTrackerGoal,
+  executeUpdateTimeTrackerGoal,
+} from './timer-goal-mutations';
+export type { TimerSession } from './timer-mutation-types';
+export {
+  executeCreateTimeTrackingEntry,
+  executeDeleteTimeTrackingSession,
+  executeMoveTimeTrackingSession,
+  executeStartTimer,
+  executeStopTimer,
+  executeUpdateTimeTrackingSession,
+} from './timer-session-mutations';

package/src/tools/executors/timer/timer-queries.ts

@@ -0,0 +1,18 @@
+export {
+  executeListTimeTrackingCategories,
+  type TimeTrackingCategoryRow,
+} from './timer-categories-executor';
+export {
+  executeGetTimeTrackerGoals,
+  normalizeCategory,
+  type TimeTrackerGoalRow,
+} from './timer-goals-executor';
+export {
+  executeGetTimeTrackingSession,
+  executeListTimeTrackingSessions,
+} from './timer-sessions-executor';
+export {
+  executeGetTimeTrackerStats,
+  fetchTimeTrackerStats,
+  type TimeTrackerStatsRow,
+} from './timer-stats-executor';

package/src/tools/executors/timer/timer-session-lifecycle.ts

@@ -0,0 +1,299 @@
+import type { MiraToolContext } from '../../mira-tools';
+import { getWorkspaceContextWorkspaceId } from '../../workspace-context';
+import { hasTaskAccess, hasTimeTrackingCategoryAccess } from '../scope-helpers';
+import {
+  coerceOptionalString,
+  MIN_DURATION_SECONDS,
+  parseFlexibleDateTime,
+  shouldRequireApproval,
+} from './timer-helpers';
+import {
+  type CreateTimeTrackingEntryArgs,
+  createTimeTrackingEntryArgsSchema,
+  getZodErrorMessage,
+  type StartTimerArgs,
+  type StopTimerArgs,
+  startTimerArgsSchema,
+  stopTimerArgsSchema,
+} from './timer-mutation-schemas';
+import {
+  type CreateTimeTrackingEntryResult,
+  type StartTimerResult,
+  type StopTimerResult,
+  toTimerSession,
+} from './timer-mutation-types';
+
+export async function executeStartTimer(
+  args: Record<string, unknown>,
+  ctx: MiraToolContext
+): Promise<StartTimerResult> {
+  let parsedArgs: StartTimerArgs;
+  try {
+    parsedArgs = startTimerArgsSchema.parse(args);
+  } catch (error) {
+    return { error: getZodErrorMessage(error) };
+  }
+
+  const workspaceId = getWorkspaceContextWorkspaceId(ctx);
+  const title = parsedArgs.title;
+  const now = new Date();
+
+  const { data: runningSessions, error: runningSelectError } =
+    await ctx.supabase
+      .from('time_tracking_sessions')
+      .select('id, start_time')
+      .eq('user_id', ctx.userId)
+      .eq('ws_id', workspaceId)
+      .eq('is_running', true);
+
+  if (runningSelectError) return { error: runningSelectError.message };
+
+  for (const runningSession of runningSessions ?? []) {
+    const runningStartTime = new Date(runningSession.start_time);
+    const durationSeconds = Number.isNaN(runningStartTime.getTime())
+      ? 0
+      : Math.max(
+          0,
+          Math.floor((now.getTime() - runningStartTime.getTime()) / 1000)
+        );
+
+    const { data: stoppedRows, error: stopError } = await ctx.supabase
+      .from('time_tracking_sessions')
+      .update({
+        is_running: false,
+        end_time: now.toISOString(),
+        duration_seconds: durationSeconds,
+      })
+      .eq('id', runningSession.id)
+      .eq('user_id', ctx.userId)
+      .eq('ws_id', workspaceId)
+      .eq('is_running', true)
+      .select('id');
+
+    if (stopError) {
+      return {
+        error: `Failed to stop running timer before starting a new one: ${stopError.message}`,
+      };
+    }
+
+    if (!stoppedRows?.length) {
+      return {
+        error:
+          'Failed to stop running timer before starting a new one: no session was updated',
+      };
+    }
+  }
+
+  const { data: session, error } = await ctx.supabase
+    .from('time_tracking_sessions')
+    .insert({
+      title,
+      description: coerceOptionalString(parsedArgs.description),
+      start_time: now.toISOString(),
+      is_running: true,
+      user_id: ctx.userId,
+      ws_id: workspaceId,
+    })
+    .select('id, title, start_time')
+    .single();
+
+  if (error) return { error: error.message };
+  return {
+    success: true,
+    message: `Timer started: "${title}"`,
+    session: toTimerSession(session as Record<string, unknown>),
+  };
+}
+
+export async function executeStopTimer(
+  args: Record<string, unknown>,
+  ctx: MiraToolContext
+): Promise<StopTimerResult> {
+  let parsedArgs: StopTimerArgs;
+  try {
+    parsedArgs = stopTimerArgsSchema.parse(args);
+  } catch (error) {
+    return { error: getZodErrorMessage(error) };
+  }
+
+  const workspaceId = getWorkspaceContextWorkspaceId(ctx);
+  const sessionId = coerceOptionalString(parsedArgs.sessionId);
+
+  let query = ctx.supabase
+    .from('time_tracking_sessions')
+    .select('id, title, start_time')
+    .eq('user_id', ctx.userId)
+    .eq('ws_id', workspaceId)
+    .eq('is_running', true);
+
+  if (sessionId) query = query.eq('id', sessionId);
+
+  const { data: session, error: sessionError } = await query
+    .limit(1)
+    .maybeSingle();
+
+  if (sessionError) return { error: sessionError.message };
+  if (!session) return { error: 'No running timer found' };
+
+  const endTime = new Date();
+  const startTime = new Date(session.start_time);
+  const durationSeconds = Math.round(
+    (endTime.getTime() - startTime.getTime()) / 1000
+  );
+
+  const { data: stoppedRows, error } = await ctx.supabase
+    .from('time_tracking_sessions')
+    .update({
+      is_running: false,
+      end_time: endTime.toISOString(),
+      duration_seconds: durationSeconds,
+    })
+    .eq('id', session.id)
+    .eq('user_id', ctx.userId)
+    .eq('ws_id', workspaceId)
+    .eq('is_running', true)
+    .select(
+      `
+      *,
+      category:time_tracking_categories(*),
+      task:tasks(*)
+    `
+    )
+    .single();
+
+  if (error) return { error: error.message };
+  if (!stoppedRows) {
+    return { error: 'Failed to stop timer: no running session was updated' };
+  }
+
+  const hours = Math.floor(durationSeconds / 3600);
+  const minutes = Math.floor((durationSeconds % 3600) / 60);
+
+  return {
+    success: true,
+    message: `Timer stopped: "${session.title}" — ${hours}h ${minutes}m`,
+    session: toTimerSession(stoppedRows as Record<string, unknown>, {
+      durationSeconds,
+      durationFormatted: `${hours}h ${minutes}m`,
+    }),
+  };
+}
+
+export async function executeCreateTimeTrackingEntry(
+  args: Record<string, unknown>,
+  ctx: MiraToolContext
+): Promise<CreateTimeTrackingEntryResult> {
+  let parsedArgs: CreateTimeTrackingEntryArgs;
+  try {
+    parsedArgs = createTimeTrackingEntryArgsSchema.parse(args);
+  } catch (error) {
+    return { error: getZodErrorMessage(error) };
+  }
+
+  const workspaceId = getWorkspaceContextWorkspaceId(ctx);
+  const title = parsedArgs.title;
+
+  const startParsed = parseFlexibleDateTime(parsedArgs.startTime, 'startTime', {
+    date: parsedArgs.date,
+    timezone: ctx.timezone,
+  });
+  if (!startParsed.ok) return { error: startParsed.error };
+  const endParsed = parseFlexibleDateTime(parsedArgs.endTime, 'endTime', {
+    date: parsedArgs.date,
+    timezone: ctx.timezone,
+  });
+  if (!endParsed.ok) return { error: endParsed.error };
+
+  const startTime = startParsed.value;
+  const endTime = endParsed.value;
+  if (endTime <= startTime) {
+    return { error: 'endTime must be after startTime' };
+  }
+
+  const durationSeconds = Math.floor(
+    (endTime.getTime() - startTime.getTime()) / 1000
+  );
+  if (durationSeconds < MIN_DURATION_SECONDS) {
+    return { error: 'Session must be at least 1 minute long' };
+  }
+
+  const approvalCheck = await shouldRequireApproval(startTime, ctx);
+  if (approvalCheck.requiresApproval) {
+    return {
+      success: true,
+      requiresApproval: true,
+      requestCreated: false,
+      message:
+        `${approvalCheck.reason ?? 'This missed entry requires approval.'} ` +
+        'No request has been created yet.',
+      nextStep:
+        'Inform the user to upload proof images and submit a time tracking request to complete this entry.',
+      approvalRequest: {
+        startTime: startTime.toISOString(),
+        endTime: endTime.toISOString(),
+        titleHint: title,
+        descriptionHint: coerceOptionalString(parsedArgs.description),
+      },
+    };
+  }
+
+  const categoryId = coerceOptionalString(parsedArgs.categoryId);
+  if (categoryId) {
+    try {
+      if (!(await hasTimeTrackingCategoryAccess(ctx, categoryId))) {
+        return { error: 'Category not found in current workspace' };
+      }
+    } catch (error) {
+      return {
+        error:
+          error instanceof Error ? error.message : 'Category lookup failed',
+      };
+    }
+  }
+
+  const taskId = coerceOptionalString(parsedArgs.taskId);
+  if (taskId) {
+    try {
+      if (!(await hasTaskAccess(ctx, taskId))) {
+        return { error: 'Task not found in current workspace' };
+      }
+    } catch (error) {
+      return {
+        error: error instanceof Error ? error.message : 'Task lookup failed',
+      };
+    }
+  }
+
+  const { data, error } = await ctx.supabase
+    .from('time_tracking_sessions')
+    .insert({
+      ws_id: workspaceId,
+      user_id: ctx.userId,
+      title,
+      description: coerceOptionalString(parsedArgs.description),
+      category_id: categoryId,
+      task_id: taskId,
+      start_time: startTime.toISOString(),
+      end_time: endTime.toISOString(),
+      duration_seconds: durationSeconds,
+      is_running: false,
+      pending_approval: false,
+    })
+    .select(
+      `
+      *,
+      category:time_tracking_categories(*),
+      task:tasks(*)
+    `
+    )
+    .single();
+
+  if (error) return { error: error.message };
+
+  return {
+    success: true,
+    requiresApproval: false,
+    message: 'Time tracking entry created.',
+    session: toTimerSession(data as Record<string, unknown>),
+  };
+}