npm package: @mrck-labs/vanaheim-shared
Description: Shared types, constants, and utilities for Vanaheim apps
Author: Marc Kraw
Latest version: 0.7.0

# @mrck-labs/vanaheim-shared

> Shared types, constants, utilities, and state management for the Vanaheim ecosystem

This package provides common code used by both **Vanaheim Desktop** (Electron) and **MobileHorizon** (React Native/Expo).

## Installation

```bash
npm install @mrck-labs/vanaheim-shared
```

**Peer Dependencies:**

- `jotai` (optional) - Required only if using the `/atoms` module

## Modules

### Types (`/types`)

Database entity types matching the Supabase schema:

```typescript
import type {
  // Focus
  FocusSession,
  NewFocusSession,
  FocusCategory,
  FocusSessionFilters,

  // Expenses & Income
  Expense,
  NewExpense,
  ExpenseCategory,
  Income,
  NewIncome,
  IncomeCategory,

  // Health
  HealthHabit,
  HealthCategory,
  HealthCompletion,

  // And more...
} from "@mrck-labs/vanaheim-shared/types";
```

### Constants (`/constants`)

Shared constants and enums:

```typescript
import {
  CURRENCIES, // ['CHF', 'USD', 'EUR', 'PLN']
  CURRENCY_SYMBOLS, // { CHF: 'CHF', USD: '$', ... }
  FREQUENCIES, // ['monthly', 'yearly', '6-monthly', ...]
  DEFAULT_FOCUS_DURATIONS, // [15, 25, 30, 45, 60, 90]
  FOCUS_STATUS, // ['active', 'completed', 'abandoned']
  SETTING_KEYS,
  API_URLS,
} from "@mrck-labs/vanaheim-shared/constants";
```

### Utilities (`/utils`)

Common utility functions:

```typescript
import {
  formatTime, // (seconds) => "02:05"
  formatTotalTime, // (seconds) => "1h 30m"
  formatCurrency, // (amount, currency) => "CHF 1'234.56"
  formatRelativeTime, // (dateStr) => "2h ago"
  generateId, // () => UUID v4
  truncate, // (str, maxLength) => "Hello..."
} from "@mrck-labs/vanaheim-shared/utils";
```

### Query Keys (`/query`)

Centralized TanStack Query cache key factory:

```typescript
import { queryKeys } from "@mrck-labs/vanaheim-shared/query";

// In query hooks
useQuery({ queryKey: queryKeys.focusSessions.today() });
useQuery({ queryKey: queryKeys.expenses.list({ isActive: true }) });

// Invalidating
queryClient.invalidateQueries({ queryKey: queryKeys.focusSessions.all });
```

**Covered modules:** `expenses`, `expenseCategories`, `expensePayments`, `incomes`, `incomeCategories`, `incomePayments`, `exchangeRates`, `focusSessions`, `focusCategories`, `settings`, `lieuDays`, `efLinks`, `bankConnections`, `bankTransactions`, `healthCategories`, `healthHabits`, `healthCompletions`, `healthStats`, `promptCategories`, `promptLabels`, `prompts`, `trainingActivities`, `trainingSessions`, `plannedSessions`, `races`, `trainingStats`, `strava`, `journalEntries`, `journalData`, `chatConversations`, `chatMessages`, `googleCalendar`, `linear`

### Focus Atoms (`/atoms`)

Jotai atoms for focus timer state management:

```typescript
import {
  // Types
  type TimerStatus, // 'idle' | 'running' | 'paused' | 'completed'
  type ActiveSession,

  // Core atoms
  timerStatusAtom,
  targetSecondsAtom,
  elapsedSecondsAtom,
  activeSessionAtom,

  // Derived atoms
  remainingSecondsAtom,
  progressAtom, // 0 to 1
  progressPercentAtom, // 0 to 100
  formattedRemainingAtom, // "24:59"
  formattedElapsedAtom, // "00:01"
} from "@mrck-labs/vanaheim-shared/atoms";
```

### Date Utilities (`/date`)

Comprehensive date manipulation:

```typescript
import {
  // Core
  getTodayString, // "2024-12-16"
  parseLocalDate, // Avoids timezone issues
  formatDateString, // Date => "2024-12-16"

  // Checks
  isToday,
  isOverdue,
  isDueSoon, // Within N days

  // Arithmetic
  addDays,
  subtractDays,
  getYesterdayString,
  getTomorrowString,

  // ISO helpers (for DB queries)
  getStartOfDayISO,
  getEndOfDayISO,

  // Week utilities
  getWeekStartString,
  getWeekEndString,
  formatWeekRange,

  // Display formatting
  formatFullDate, // "Monday, December 15, 2024"
  formatDateHeader, // "Today" | "Tomorrow" | "Overdue"
  formatRelativeDueDate, // "Due in 3 days"
} from "@mrck-labs/vanaheim-shared/date";
```

## Usage in Projects

### Vanaheim Desktop

```typescript
// src/lib/queryClient.ts
export { queryKeys } from '@mrck-labs/vanaheim-shared/query'

// src/atoms/focus.ts
export { timerStatusAtom, ... } from '@mrck-labs/vanaheim-shared/atoms'
```

### MobileHorizon

```typescript
// src/hooks/queries/useFocusQueries.ts
import { queryKeys } from '@mrck-labs/vanaheim-shared/query'

// src/atoms/focus.ts
export { timerStatusAtom, ... } from '@mrck-labs/vanaheim-shared/atoms'
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Type check
npm run typecheck

# Clean build artifacts
npm run clean
```

## Release

This package uses [changesets](https://github.com/changesets/changesets) for version management.

See [RELEASE_GUIDE.md](./RELEASE_GUIDE.md) for detailed release instructions.

## License

MIT