@deskup-app/core

Core reminder engine, data models, and business logic for DeskUp applications.

Platform-agnostic TypeScript library that powers all DeskUp clients (desktop, browser extension, mobile).

Installation

npm install @deskup-app/core
# or
pnpm add @deskup-app/core
# or
yarn add @deskup-app/core

Quick Start

import {
  DeskUpApp,
  MemoryStorage,
  ConsoleNotification,
} from "@deskup-app/core";

// Create app with storage and notification implementations
const app = new DeskUpApp({
  storage: new MemoryStorage(),
  notifications: new ConsoleNotification(),
});

// Initialize and start
await app.initialize();
await app.start();

// Check status
const status = app.getStatus();
console.log(`Next reminder in ${status.nextReminderInSeconds} seconds`);

Architecture

@deskup-app/core
├── domain/
│   ├── reminder/      # Reminder engine, types, scheduling
│   └── settings/      # Settings model, validation, migration
├── infrastructure/
│   ├── storage/       # Storage port interface
│   └── notifications/ # Notification port interface
└── application/       # DeskUpApp orchestration

API Reference

DeskUpApp

Main application class that orchestrates all components.

const app = new DeskUpApp({
  storage: StoragePort,           // Required: persistence implementation
  notifications?: NotificationPort, // Optional: notification implementation
  onReminderEvent?: (event) => void, // Optional: event callback
  onSettingsChange?: (settings) => void, // Optional: settings callback
});

await app.initialize();  // Load settings
await app.start();       // Start reminders
await app.pause();       // Pause reminders
await app.resume();      // Resume reminders
app.stop();              // Stop reminders

app.getStatus();         // Get current status
app.getSettings();       // Get current settings
await app.setInterval(30); // Set reminder interval (minutes)

ReminderEngine

Low-level engine for direct control.

import { ReminderEngine } from "@deskup-app/core";

const engine = new ReminderEngine({
  schedule: ReminderSchedule,
  notificationPort?: NotificationPort,
  timeProvider?: TimeProvider,
  onEvent?: (event) => void,
});

engine.start();
engine.pause();
engine.resume();
engine.stop();
engine.getStatus();

Settings

import {
  createDefaultSettings,
  validateSettings,
  SettingsManager,
} from "@deskup-app/core";

// Get defaults
const settings = createDefaultSettings();

// Validate
const result = validateSettings(settings);
if (!result.valid) {
  console.error(result.errors);
}

// Use manager for persistence
const manager = new SettingsManager({ storage });
await manager.loadSettings();
await manager.saveSettings(settings);

Platform Ports

Implement these interfaces for your platform:

StoragePort

interface StoragePort {
  saveSettings(settings: Settings): Promise<void>;
  loadSettings(): Promise<Settings | null>;
  saveBreak(breakRecord: Break): Promise<void>;
  loadBreakHistory(query?: BreakHistoryQuery): Promise<Break[]>;
  clearAll(): Promise<void>;
  isAvailable(): Promise<boolean>;
}

NotificationPort

interface NotificationPort {
  show(notification: Notification): Promise<NotificationResult>;
  close(notificationId: string): Promise<void>;
  requestPermission(): Promise<boolean>;
  hasPermission(): Promise<boolean>;
  isSupported(): boolean;
}

Types

ReminderSchedule

interface ReminderSchedule {
  microBreaks: BreakConfig;  // 20 seconds
  shortBreaks: BreakConfig;  // 2-5 minutes
  longBreaks: BreakConfig;   // 10-15 minutes
  activeHours?: ActiveHours;
  idleDetection: IdleDetection;
}

Settings

interface Settings {
  version: number;
  schedule: ReminderSchedule;
  notifications: NotificationSettings;
  exercises: ExerciseSettings;
  privacy: PrivacySettings;
  appearance: AppearanceSettings;
  isPaused: boolean;
}

Testing

The library includes mock implementations for testing:

import {
  MemoryStorage,
  MockNotification,
  MockTime,
} from "@deskup-app/core";

// In-memory storage
const storage = new MemoryStorage();

// Mock notifications
const notifications = new MockNotification();
notifications.notifications; // Array of sent notifications

// Mock time provider
const time = new MockTime(new Date("2025-01-01T10:00:00"));
time.advanceMinutes(30);

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test

# Watch mode
pnpm dev

License

MIT