/**
 * Core Contracts
 * 
 * Shared interfaces and record shapes for cross-platform contracts.
 * These represent wire-level contracts that cross JS ↔ native boundaries
 * and are persisted long-term.
 * 
 * @author Matthew Raymer
 * @version 1.0.0
 */

import type {
  ScheduleKind,
  HistoryKind,
  HistoryOutcome,
  CallbackKind,
  ConfigDataType,
} from './enums';

/**
 * Recurring schedule pattern stored in database
 * Used to restore schedules after device reboot
 */
export interface Schedule {
  /** Unique schedule identifier */
  id: string;
  /** Schedule type: 'fetch' for content fetching, 'notify' for notifications */
  kind: ScheduleKind;
  /** Cron expression (e.g., "0 9 * * *" for daily at 9 AM) */
  cron?: string;
  /** Clock time in HH:mm format (e.g., "09:00") */
  clockTime?: string;
  /** Whether schedule is enabled */
  enabled: boolean;
  /** Timestamp of last execution (milliseconds since epoch) */
  lastRunAt?: number;
  /** Timestamp of next scheduled execution (milliseconds since epoch) */
  nextRunAt?: number;
  /** Random jitter in milliseconds for timing variation */
  jitterMs: number;
  /** Backoff policy ('exp' for exponential, etc.) */
  backoffPolicy: string;
  /** Optional JSON state for advanced scheduling */
  stateJson?: string;
}

/**
 * Schedule with AlarmManager status
 * Extends Schedule with isActuallyScheduled flag indicating if alarm is registered in AlarmManager
 */
export interface ScheduleWithStatus extends Schedule {
  /** Whether the alarm is actually scheduled in AlarmManager (Android only, for 'notify' schedules) */
  isActuallyScheduled: boolean;
  /** Status of the schedule */
  status: 'active' | 'paused' | 'error';
}

/**
 * Input type for creating a new schedule
 */
export interface CreateScheduleInput {
  kind: ScheduleKind;
  cron?: string;
  clockTime?: string;
  enabled?: boolean;
  jitterMs?: number;
  backoffPolicy?: string;
  stateJson?: string;
}

/**
 * Content cache entry with TTL
 * Stores prefetched content for offline-first display
 */
export interface ContentCache {
  /** Unique cache identifier */
  id: string;
  /** Timestamp when content was fetched (milliseconds since epoch) */
  fetchedAt: number;
  /** Time-to-live in seconds */
  ttlSeconds: number;
  /** Content payload (JSON string or base64 encoded) */
  payload: string;
  /** Optional metadata */
  meta?: string;
}

/**
 * Input type for creating a content cache entry
 */
export interface CreateContentCacheInput {
  id?: string; // Auto-generated if not provided
  payload: string;
  ttlSeconds: number;
  meta?: string;
}

/**
 * Plugin configuration entry
 * Stores user preferences and plugin settings
 */
export interface Config {
  /** Unique configuration identifier */
  id: string;
  /** Optional TimeSafari DID for user-specific configs */
  timesafariDid?: string;
  /** Configuration type (e.g., 'plugin_setting', 'user_preference') */
  configType: string;
  /** Configuration key */
  configKey: string;
  /** Configuration value (stored as string, parsed based on configDataType) */
  configValue: string;
  /** Data type: 'string' | 'boolean' | 'integer' | 'long' | 'float' | 'double' | 'json' */
  configDataType: ConfigDataType;
  /** Whether value is encrypted */
  isEncrypted: boolean;
  /** Timestamp when config was created (milliseconds since epoch) */
  createdAt: number;
  /** Timestamp when config was last updated (milliseconds since epoch) */
  updatedAt: number;
}

/**
 * Input type for creating a configuration entry
 */
export interface CreateConfigInput {
  id?: string; // Auto-generated if not provided
  timesafariDid?: string;
  configType: string;
  configKey: string;
  configValue: string;
  configDataType?: ConfigDataType; // Defaults to 'string' if not provided
  isEncrypted?: boolean;
}

/**
 * Callback configuration
 * Stores callback endpoint configurations for execution after events
 */
export interface Callback {
  /** Unique callback identifier */
  id: string;
  /** Callback type: 'http' for HTTP requests, 'local' for local handlers, 'queue' for queue */
  kind: CallbackKind;
  /** Target URL or identifier */
  target: string;
  /** Optional JSON headers for HTTP callbacks */
  headersJson?: string;
  /** Whether callback is enabled */
  enabled: boolean;
  /** Timestamp when callback was created (milliseconds since epoch) */
  createdAt: number;
}

/**
 * Input type for creating a callback configuration
 */
export interface CreateCallbackInput {
  id: string;
  kind: CallbackKind;
  target: string;
  headersJson?: string;
  enabled?: boolean;
}

/**
 * Execution history entry
 * Logs fetch/notify/callback execution for debugging and analytics
 */
export interface History {
  /** Auto-incrementing history ID */
  id: number;
  /** Reference ID (content ID, schedule ID, etc.) */
  refId: string;
  /** Execution kind: 'fetch' | 'notify' | 'callback' | 'boot_recovery' */
  kind: HistoryKind;
  /** Timestamp when execution occurred (milliseconds since epoch) */
  occurredAt: number;
  /** Execution duration in milliseconds */
  durationMs?: number;
  /** Outcome: 'success' | 'failure' | 'skipped_ttl' | 'circuit_open' */
  outcome: HistoryOutcome;
  /** Optional JSON diagnostics */
  diagJson?: string;
}

/**
 * History statistics
 */
export interface HistoryStats {
  /** Total number of history entries */
  totalCount: number;
  /** Count by outcome */
  outcomes: Record<string, number>;
  /** Count by kind */
  kinds: Record<string, number>;
  /** Most recent execution timestamp */
  mostRecent?: number;
  /** Oldest execution timestamp */
  oldest?: number;
}

