smartupdate/ts/smartupdate.interfaces.ts

import type { TLogLevel } from './smartupdate.constants.js';
import type * as smartnpm from '@push.rocks/smartnpm';

export type TCacheStrategy = 'always' | 'never' | 'time-based';
export type TCacheStoreType = 'custom' | 'userHomeDir' | 'ephemeral';
export type TCachedUpdateStatus = 'up-to-date' | 'update-available';

/**
 * Cache status stored for each package
 */
export interface ICacheStatus {
  lastCheck: number;
  latestVersion: string;
  currentVersion?: string;
  registryUrl?: string;
  status?: TCachedUpdateStatus;
  performedUpgrade: boolean;
}

/**
 * Options for configuring the SmartUpdate instance
 */
export interface ISmartUpdateOptions {
  /**
   * Options for the npm registry connection
   */
  npmRegistryOptions?: smartnpm.INpmRegistryConstructorOptions;

  /**
   * Cache duration configuration
   * @default { hours: 1 }
   */
  cacheDuration?: {
    hours?: number;
    minutes?: number;
    seconds?: number;
  };

  /**
   * Logging level
   * @default 'INFO'
   */
  logLevel?: TLogLevel;

  /**
   * Custom logger function
   * If provided, this will be used instead of console output
   */
  customLogger?: (level: TLogLevel, message: string) => void;

  /**
   * Disable colored output
   * @default false
   */
  noColor?: boolean;

  /**
   * Cache storage configuration
   * @default { storeType: 'userHomeDir', storeIdentifier: 'global_smartupdate' }
   */
  cacheStore?: {
    storeType?: TCacheStoreType;
    storeIdentifier?: string;
    customPath?: string;
  };
}

/**
 * Options for checking for updates
 */
export interface IUpdateCheckOptions {
  /**
   * The npm package name to check
   */
  packageName: string;

  /**
   * The current version to compare against
   */
  currentVersion: string;

  /**
   * Optional URL to the changelog
   * If provided and an update is available, the changelog will be opened
   */
  changelogUrl?: string;

  /**
   * Whether to open the changelog URL automatically
   * Only applies if running in a non-CI environment
   * @default true
   */
  openChangelog?: boolean;

  /**
   * Cache strategy for this check
   * - 'always': Always use an existing matching cache entry
   * - 'never': Always check registry, bypass cache
   * - 'time-based': Check based on cache duration
   * @default 'time-based'
   */
  cacheStrategy?: TCacheStrategy;
}

/**
 * Result of an update check
 */
export interface IUpdateCheckResult {
  /**
   * Status of the update check
   */
  status: 'up-to-date' | 'update-available' | 'check-skipped' | 'error';

  /**
   * The current version being checked
   */
  currentVersion: string;

  /**
   * The latest version available (if found)
   */
  latestVersion?: string;

  /**
   * The package name that was checked
   */
  packageName: string;

  /**
   * Time when the check was performed
   */
  checkTime: Date;

  /**
   * Whether this result came from cache
   */
  cacheHit: boolean;

  /**
   * When the next check can be performed (if check was skipped due to rate limiting)
   */
  nextCheckTime?: Date;

  /**
   * Error details if status is 'error'
   */
  error?: Error;

  /**
   * Reason for the result (human-readable explanation)
   */
  reason?: string;
}

/**
 * Options for the cache manager
 */
export interface ICacheOptions {
  /**
   * Cache duration in milliseconds
   */
  durationMs: number;

  /**
   * Identifier for the key-value store
   */
  storeIdentifier?: string;

  /**
   * Key-value store backend
   */
  storeType?: TCacheStoreType;

  /**
   * Custom path for custom key-value stores
   */
  customPath?: string;
}

/**
 * Options for the notifier
 */
export interface INotificationOptions {
  /**
   * Log level for notifications
   */
  logLevel: TLogLevel;

  /**
   * Whether to use colors in output
   */
  useColors: boolean;

  /**
   * Custom logger function
   */
  customLogger?: (level: TLogLevel, message: string) => void;
}