@rs-native-kit/version-check 0.1.2

package/src/presentation/components/OptionalUpdateBanner.tsx

@@ -0,0 +1,53 @@
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import type { ReactElement } from 'react';
+import type { UpdateInfo } from '../../domain/models/UpdateInfo';
+
+export interface OptionalUpdateBannerProps {
+  updateInfo: UpdateInfo;
+  onUpdatePress: () => void;
+  onDismissPress: () => void;
+  message?: string;
+  updateButtonLabel?: string;
+}
+
+/** Low-intrusion in-app banner (Prompt 1 §5.3; UI copy detail is Prompt 19). */
+export function OptionalUpdateBanner({
+  updateInfo,
+  onUpdatePress,
+  onDismissPress,
+  message = `Version ${updateInfo.latestVersion} is available.`,
+  updateButtonLabel = 'Update',
+}: OptionalUpdateBannerProps): ReactElement {
+  return (
+    <View style={styles.banner}>
+      <Text style={styles.message}>{message}</Text>
+      <View style={styles.actions}>
+        <Pressable onPress={onUpdatePress} accessibilityRole="button">
+          <Text style={styles.updateLabel}>{updateButtonLabel}</Text>
+        </Pressable>
+        <Pressable
+          onPress={onDismissPress}
+          accessibilityRole="button"
+          accessibilityLabel="Dismiss"
+        >
+          <Text style={styles.dismissLabel}>✕</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  banner: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingVertical: 10,
+    paddingHorizontal: 16,
+    backgroundColor: '#111827',
+  },
+  message: { color: '#ffffff', fontSize: 13, flexShrink: 1, marginRight: 12 },
+  actions: { flexDirection: 'row', alignItems: 'center', gap: 16 },
+  updateLabel: { color: '#60a5fa', fontSize: 13, fontWeight: '700' },
+  dismissLabel: { color: '#9ca3af', fontSize: 13 },
+});

package/src/presentation/components/SoftUpdateDialog.tsx

@@ -0,0 +1,84 @@
+import { Modal, Pressable, StyleSheet, Text, View } from 'react-native';
+import type { ReactElement } from 'react';
+import type { UpdateInfo } from '../../domain/models/UpdateInfo';
+
+export interface SoftUpdateDialogProps {
+  updateInfo: UpdateInfo;
+  onUpdatePress: () => void;
+  onLaterPress: () => void;
+  title?: string;
+  message?: string;
+  updateButtonLabel?: string;
+  laterButtonLabel?: string;
+}
+
+/** Dismissible modal dialog (Prompt 1 §5.3; UI copy detail is Prompt 19). */
+export function SoftUpdateDialog({
+  updateInfo,
+  onUpdatePress,
+  onLaterPress,
+  title = 'Update Available',
+  message = `Version ${updateInfo.latestVersion} is available.${updateInfo.releaseNotes ? ` ${updateInfo.releaseNotes}` : ''}`,
+  updateButtonLabel = 'Update',
+  laterButtonLabel = 'Later',
+}: SoftUpdateDialogProps): ReactElement {
+  return (
+    <Modal
+      visible
+      animationType="slide"
+      transparent
+      onRequestClose={onLaterPress}
+    >
+      <View style={styles.backdrop}>
+        <View style={styles.card}>
+          <Text style={styles.title}>{title}</Text>
+          <Text style={styles.message}>{message}</Text>
+          <View style={styles.actions}>
+            <Pressable
+              style={styles.secondaryButton}
+              onPress={onLaterPress}
+              accessibilityRole="button"
+            >
+              <Text style={styles.secondaryButtonLabel}>
+                {laterButtonLabel}
+              </Text>
+            </Pressable>
+            <Pressable
+              style={styles.primaryButton}
+              onPress={onUpdatePress}
+              accessibilityRole="button"
+            >
+              <Text style={styles.primaryButtonLabel}>{updateButtonLabel}</Text>
+            </Pressable>
+          </View>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  backdrop: {
+    flex: 1,
+    backgroundColor: 'rgba(0,0,0,0.4)',
+    justifyContent: 'flex-end',
+  },
+  card: {
+    backgroundColor: '#ffffff',
+    borderTopLeftRadius: 16,
+    borderTopRightRadius: 16,
+    padding: 24,
+  },
+  title: { fontSize: 18, fontWeight: '700', marginBottom: 8 },
+  message: { fontSize: 14, marginBottom: 20 },
+  actions: { flexDirection: 'row', justifyContent: 'flex-end', gap: 12 },
+  secondaryButton: { paddingVertical: 10, paddingHorizontal: 16 },
+  secondaryButtonLabel: { color: '#6b7280', fontSize: 15, fontWeight: '600' },
+  primaryButton: {
+    paddingVertical: 10,
+    paddingHorizontal: 16,
+    borderRadius: 8,
+    backgroundColor: '#2563eb',
+  },
+  primaryButtonLabel: { color: '#ffffff', fontSize: 15, fontWeight: '600' },
+});

package/src/presentation/hooks/VersionManagerProvider.tsx

@@ -0,0 +1,23 @@
+import { useMemo } from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import { VersionManager } from '../../publicApi';
+import type { VersionManagerOptions } from '../../domain/models/VersionManagerOptions';
+import { VersionManagerContext } from './context';
+
+export interface VersionManagerProviderProps {
+  options: VersionManagerOptions;
+  children: ReactNode;
+}
+
+/** Optional top-level configuration provider (Prompt 2 §6) — an alternative to passing options to every useVersionManager() call. */
+export function VersionManagerProvider({
+  options,
+  children,
+}: VersionManagerProviderProps): ReactElement {
+  const manager = useMemo(() => VersionManager.configure(options), [options]);
+  return (
+    <VersionManagerContext.Provider value={manager}>
+      {children}
+    </VersionManagerContext.Provider>
+  );
+}

package/src/presentation/hooks/context.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+import type { IVersionManagerCore } from '../../domain/IVersionManagerCore';
+
+export const VersionManagerContext = createContext<IVersionManagerCore | null>(
+  null
+);

package/src/presentation/hooks/useUpdateState.ts

@@ -0,0 +1,50 @@
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from 'react';
+import type { ActionPlan } from '../../domain/models/ActionPlan';
+import type { LifecycleState } from '../../domain/models/LifecycleState';
+import type { UpdateInfo } from '../../domain/models/UpdateInfo';
+import { VersionManager } from '../../publicApi';
+import { VersionManagerStore } from '../state/VersionManagerStore';
+import { VersionManagerContext } from './context';
+
+export interface UseUpdateStateResult {
+  readonly state: LifecycleState;
+  readonly updateInfo: UpdateInfo | null;
+  readonly isUpdateAvailable: boolean;
+  readonly actionPlan: ActionPlan | null;
+}
+
+/**
+ * Reactive state only, for components that don't need to trigger checks (Prompt 2 §6).
+ * Must be used beneath a tree where useVersionManager() or VersionManagerProvider has
+ * already run at least once — otherwise this falls back to VersionManager.getInstance(),
+ * which throws NotInitializedException if configure() was never called.
+ */
+export function useUpdateState(): UseUpdateStateResult {
+  const contextManager = useContext(VersionManagerContext);
+  const manager = useMemo(
+    () => contextManager ?? VersionManager.getInstance(),
+    [contextManager]
+  );
+
+  const store = useMemo(() => new VersionManagerStore(manager), [manager]);
+  useEffect(() => () => store.dispose(), [store]);
+
+  const uiState = useSyncExternalStore(
+    useCallback((listener) => store.subscribe(listener), [store]),
+    () => store.getState(),
+    () => store.getState()
+  );
+
+  return {
+    state: uiState.lifecycleState,
+    updateInfo: uiState.updateInfo,
+    isUpdateAvailable: uiState.isUpdateAvailable,
+    actionPlan: uiState.actionPlan,
+  };
+}

package/src/presentation/hooks/useVersionManager.ts

@@ -0,0 +1,68 @@
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from 'react';
+import type { IVersionManagerCore } from '../../domain/IVersionManagerCore';
+import type { LifecycleState } from '../../domain/models/LifecycleState';
+import type { ActionPlan } from '../../domain/models/ActionPlan';
+import type { CheckForUpdatesOptions } from '../../domain/models/PublicApiOptions';
+import type { UpdateInfo } from '../../domain/models/UpdateInfo';
+import type { VersionManagerOptions } from '../../domain/models/VersionManagerOptions';
+import { VersionManager } from '../../publicApi';
+import { VersionManagerStore } from '../state/VersionManagerStore';
+import { VersionManagerContext } from './context';
+
+export interface UseVersionManagerResult {
+  readonly manager: IVersionManagerCore;
+  readonly state: LifecycleState;
+  readonly updateInfo: UpdateInfo | null;
+  readonly isUpdateAvailable: boolean;
+  readonly checkForUpdates: (
+    options?: CheckForUpdatesOptions
+  ) => Promise<ActionPlan>;
+}
+
+/**
+ * Bootstraps (or attaches to) the singleton and returns the imperative handle plus
+ * reactive state in one call (Prompt 2 §6). For a stable manager reference across
+ * re-renders, pass a memoized `options` object — VersionManager.configure() is
+ * idempotent for equal options, but this hook still re-invokes it whenever the
+ * `options` reference changes.
+ */
+export function useVersionManager(
+  options?: VersionManagerOptions
+): UseVersionManagerResult {
+  const contextManager = useContext(VersionManagerContext);
+
+  const manager = useMemo<IVersionManagerCore>(() => {
+    if (contextManager) return contextManager;
+    if (options) return VersionManager.configure(options);
+    return VersionManager.getInstance();
+  }, [contextManager, options]);
+
+  const store = useMemo(() => new VersionManagerStore(manager), [manager]);
+  useEffect(() => () => store.dispose(), [store]);
+
+  const uiState = useSyncExternalStore(
+    useCallback((listener) => store.subscribe(listener), [store]),
+    () => store.getState(),
+    () => store.getState()
+  );
+
+  const checkForUpdates = useCallback(
+    (checkOptions?: CheckForUpdatesOptions) =>
+      manager.checkForUpdates(checkOptions),
+    [manager]
+  );
+
+  return {
+    manager,
+    state: uiState.lifecycleState,
+    updateInfo: uiState.updateInfo,
+    isUpdateAvailable: uiState.isUpdateAvailable,
+    checkForUpdates,
+  };
+}

package/src/presentation/state/VersionManagerStore.ts

@@ -0,0 +1,72 @@
+import type { ActionPlan } from '../../domain/models/ActionPlan';
+import type { LifecycleState } from '../../domain/models/LifecycleState';
+import type { UpdateInfo } from '../../domain/models/UpdateInfo';
+import type { Unsubscribe } from '../../domain/models/Unsubscribe';
+import type { IVersionManagerCore } from '../../domain/IVersionManagerCore';
+
+export interface VersionManagerUiState {
+  readonly lifecycleState: LifecycleState;
+  readonly updateInfo: UpdateInfo | null;
+  readonly actionPlan: ActionPlan | null;
+  readonly isUpdateAvailable: boolean;
+}
+
+function snapshotFrom(core: IVersionManagerCore): VersionManagerUiState {
+  return {
+    lifecycleState: core.getCurrentState(),
+    updateInfo: core.getUpdateInfo(),
+    actionPlan: core.getActionPlan(),
+    isUpdateAvailable: core.isUpdateAvailable(),
+  };
+}
+
+/**
+ * The single reactive source of truth the Hooks adapter renders from (Prompt 1 §6) —
+ * components subscribe to this store, never to the core's event bus directly. Kept in
+ * sync by re-snapshotting the core on every event it emits.
+ */
+export class VersionManagerStore {
+  private state: VersionManagerUiState;
+  private readonly listeners = new Set<
+    (state: Readonly<VersionManagerUiState>) => void
+  >();
+  private readonly detach: Unsubscribe;
+
+  constructor(private readonly core: IVersionManagerCore) {
+    this.state = snapshotFrom(core);
+
+    const unsubscribers = [
+      core.onStateChanged(() => this.sync()),
+      core.onUpdateDetected(() => this.sync()),
+      core.on('updateNotAvailable', () => this.sync()),
+    ];
+    this.detach = () => {
+      for (const unsubscribe of unsubscribers) unsubscribe();
+    };
+  }
+
+  getState(): Readonly<VersionManagerUiState> {
+    return this.state;
+  }
+
+  subscribe(
+    listener: (state: Readonly<VersionManagerUiState>) => void
+  ): Unsubscribe {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  dispose(): void {
+    this.detach();
+    this.listeners.clear();
+  }
+
+  private sync(): void {
+    this.state = snapshotFrom(this.core);
+    for (const listener of Array.from(this.listeners)) {
+      listener(this.state);
+    }
+  }
+}

package/src/publicApi.ts

@@ -0,0 +1,126 @@
+import { createVersionManagerCore } from './di/container';
+import {
+  InvalidConfigException,
+  NotInitializedException,
+} from './domain/errors/VersionManagerException';
+import type { IVersionManagerCore } from './domain/IVersionManagerCore';
+import type {
+  CacheOptions,
+  FallbackOptions,
+  LoggingOptions,
+  PolicyOptions,
+  StoreLinksOptions,
+  VersionManagerOptions,
+} from './domain/models/VersionManagerOptions';
+import type { IPlatformBridge } from './domain/ports/IPlatformBridge';
+
+let instance: IVersionManagerCore | null = null;
+let instanceOptions: VersionManagerOptions | null = null;
+
+/**
+ * Structural equality via JSON serialization — good enough to detect "the same
+ * configure() call happening twice" (e.g. duplicate provider mounts in React) without
+ * requiring callers to memoize their options object. `platformBridge` (a live object
+ * of functions) is excluded; DI overrides are expected to be stable references from
+ * advanced/testing callers, not something this check needs to compare deeply.
+ */
+function withoutPlatformBridge(
+  options: VersionManagerOptions
+): Omit<VersionManagerOptions, 'platformBridge'> {
+  const clone: VersionManagerOptions = { ...options };
+  delete clone.platformBridge;
+  return clone;
+}
+
+function optionsEqual(
+  a: VersionManagerOptions,
+  b: VersionManagerOptions
+): boolean {
+  return (
+    JSON.stringify(withoutPlatformBridge(a)) ===
+    JSON.stringify(withoutPlatformBridge(b))
+  );
+}
+
+export const VersionManager = {
+  configure(options: VersionManagerOptions): IVersionManagerCore {
+    if (instance && instanceOptions) {
+      if (optionsEqual(instanceOptions, options)) {
+        return instance;
+      }
+      throw new InvalidConfigException({
+        message:
+          'VersionManager.configure() was already called with different options. Call VersionManager.reset() first if this is intentional (e.g. in tests).',
+      });
+    }
+    const core = createVersionManagerCore(options);
+    instance = core;
+    instanceOptions = options;
+    return core;
+  },
+
+  getInstance(): IVersionManagerCore {
+    if (!instance) {
+      throw new NotInitializedException({
+        message: 'VersionManager.getInstance() called before configure()',
+      });
+    }
+    return instance;
+  },
+
+  isConfigured(): boolean {
+    return instance !== null;
+  },
+
+  /** Testing/HMR only — tears down the singleton (Prompt 2 §1.1). */
+  reset(): void {
+    instance?.dispose();
+    instance = null;
+    instanceOptions = null;
+  },
+};
+
+export class VersionManagerBuilder {
+  private options: VersionManagerOptions = { stores: {} };
+
+  private constructor() {}
+
+  static create(): VersionManagerBuilder {
+    return new VersionManagerBuilder();
+  }
+
+  withLogging(options: LoggingOptions): this {
+    this.options = { ...this.options, logging: options };
+    return this;
+  }
+
+  withCache(options: CacheOptions): this {
+    this.options = { ...this.options, cache: options };
+    return this;
+  }
+
+  withFallback(options: FallbackOptions): this {
+    this.options = { ...this.options, fallback: options };
+    return this;
+  }
+
+  withStoreLinks(options: StoreLinksOptions): this {
+    this.options = { ...this.options, stores: options };
+    return this;
+  }
+
+  withPolicy(options: PolicyOptions): this {
+    this.options = { ...this.options, policy: options };
+    return this;
+  }
+
+  /** Advanced/testing: DI override (Prompt 2 §1.1). */
+  withPlatformBridge(bridge: IPlatformBridge): this {
+    this.options = { ...this.options, platformBridge: bridge };
+    return this;
+  }
+
+  build(): IVersionManagerCore {
+    return VersionManager.configure(this.options);
+  }
+}

package/src/shared/eventbus/EventBus.ts

@@ -0,0 +1,56 @@
+import type { Unsubscribe } from '../../domain/models/Unsubscribe';
+
+export type { Unsubscribe };
+
+export interface IEventBus<TMap extends object> {
+  publish<K extends keyof TMap>(type: K, payload: TMap[K]): void;
+  subscribe<K extends keyof TMap>(
+    type: K,
+    handler: (payload: TMap[K]) => void
+  ): Unsubscribe;
+  /** Removes a handler registered via subscribe() by reference (Prompt 2 §4.2's off()). */
+  off<K extends keyof TMap>(type: K, handler: (payload: TMap[K]) => void): void;
+}
+
+type AnyHandler = (payload: unknown) => void;
+
+/**
+ * Generic typed pub/sub used for both the internal domain event flow (Prompt 1 §6)
+ * and the public IVersionManagerEvents surface (Prompt 2 §4). Copy-on-write listener
+ * snapshots on dispatch (Prompt 1 §9.2) — publishing during a concurrent
+ * subscribe/unsubscribe never races or throws.
+ */
+export class EventBus<TMap extends object> implements IEventBus<TMap> {
+  private readonly listeners = new Map<keyof TMap, Set<AnyHandler>>();
+
+  publish<K extends keyof TMap>(type: K, payload: TMap[K]): void {
+    const set = this.listeners.get(type);
+    if (!set) return;
+    for (const handler of Array.from(set)) {
+      handler(payload);
+    }
+  }
+
+  subscribe<K extends keyof TMap>(
+    type: K,
+    handler: (payload: TMap[K]) => void
+  ): Unsubscribe {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(type, set);
+    }
+    const wrapped = handler as AnyHandler;
+    set.add(wrapped);
+    return () => {
+      set?.delete(wrapped);
+    };
+  }
+
+  off<K extends keyof TMap>(
+    type: K,
+    handler: (payload: TMap[K]) => void
+  ): void {
+    this.listeners.get(type)?.delete(handler as AnyHandler);
+  }
+}

package/src/shared/logging/Logger.ts

@@ -0,0 +1,70 @@
+import type {
+  ILogSink,
+  LogEntry,
+  LogLevel,
+} from '../../domain/models/VersionManagerOptions';
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+  verbose: 5,
+};
+
+export class ConsoleLogSink implements ILogSink {
+  write(entry: LogEntry): void {
+    const line = `[VersionManager] ${entry.message}`;
+    if (entry.level === 'error') {
+      console.error(line, entry.metadata ?? {});
+    } else if (entry.level === 'warn') {
+      console.warn(line, entry.metadata ?? {});
+    } else {
+      console.info(line, entry.metadata ?? {});
+    }
+  }
+}
+
+export class Logger {
+  private level: LogLevel;
+  private readonly sink: ILogSink;
+
+  constructor(level: LogLevel, sink: ILogSink) {
+    this.level = level;
+    this.sink = sink;
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  error(message: string, metadata?: Record<string, unknown>): void {
+    this.log('error', message, metadata);
+  }
+
+  warn(message: string, metadata?: Record<string, unknown>): void {
+    this.log('warn', message, metadata);
+  }
+
+  info(message: string, metadata?: Record<string, unknown>): void {
+    this.log('info', message, metadata);
+  }
+
+  debug(message: string, metadata?: Record<string, unknown>): void {
+    this.log('debug', message, metadata);
+  }
+
+  verbose(message: string, metadata?: Record<string, unknown>): void {
+    this.log('verbose', message, metadata);
+  }
+
+  private log(
+    level: LogLevel,
+    message: string,
+    metadata?: Record<string, unknown>
+  ): void {
+    if (LEVEL_ORDER[level] > LEVEL_ORDER[this.level]) return;
+    this.sink.write({ level, message, timestamp: Date.now(), metadata });
+  }
+}

package/src/ui.tsx

@@ -0,0 +1,19 @@
+// Presentation entry point (Prompt 1 §8) — importing only 'src/index.tsx' never pulls
+// in anything below; this subpath is where React/RN UI code lives.
+
+export { useVersionManager } from './presentation/hooks/useVersionManager';
+export type { UseVersionManagerResult } from './presentation/hooks/useVersionManager';
+export { useUpdateState } from './presentation/hooks/useUpdateState';
+export type { UseUpdateStateResult } from './presentation/hooks/useUpdateState';
+export { VersionManagerProvider } from './presentation/hooks/VersionManagerProvider';
+export type { VersionManagerProviderProps } from './presentation/hooks/VersionManagerProvider';
+
+export { ForceUpdateScreen } from './presentation/components/ForceUpdateScreen';
+export type { ForceUpdateScreenProps } from './presentation/components/ForceUpdateScreen';
+export { SoftUpdateDialog } from './presentation/components/SoftUpdateDialog';
+export type { SoftUpdateDialogProps } from './presentation/components/SoftUpdateDialog';
+export { OptionalUpdateBanner } from './presentation/components/OptionalUpdateBanner';
+export type { OptionalUpdateBannerProps } from './presentation/components/OptionalUpdateBanner';
+
+export type { VersionManagerUiState } from './presentation/state/VersionManagerStore';
+export { VersionManagerStore } from './presentation/state/VersionManagerStore';