@rs-native-kit/version-check 0.1.2

package/src/domain/engines/semver/SemVerEngine.ts

@@ -0,0 +1,200 @@
+import { InvalidVersionFormatException } from '../../errors/VersionManagerException';
+import type { ParsedVersion } from '../../models/ParsedVersion';
+import type { IVersionComparator } from './IVersionComparator';
+
+/**
+ * Zero-dependency SemVer 2.0.0 parser/comparator (Prompt 1 §9.3 — no `semver` package).
+ * Supports the full strict grammar plus a small set of common looseness (leading "v",
+ * 1 or 2 part versions). Range support covers "^", "~", the comparison operators, and
+ * whitespace-separated AND clauses — OR ("||") ranges and prerelease-scoped range
+ * matching are intentionally out of scope for this pass; see Prompt 5 in the design
+ * series for the full BNF grammar and edge-case matrix this should eventually match.
+ */
+
+const STRICT_SEMVER_REGEX =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+const LOOSE_VERSION_REGEX = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\..*)?$/;
+
+function toIdentifiers(segment: string | undefined): (string | number)[] {
+  if (!segment) return [];
+  return segment.split('.').map((part) => {
+    return /^\d+$/.test(part) ? Number(part) : part;
+  });
+}
+
+export function parseVersion(raw: string): ParsedVersion {
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new InvalidVersionFormatException({
+      message: `Cannot parse version: expected a non-empty string, received "${String(raw)}"`,
+      metadata: { raw },
+    });
+  }
+
+  const trimmed = raw.trim().replace(/^[vV]/, '');
+  const strict = STRICT_SEMVER_REGEX.exec(trimmed);
+  if (strict) {
+    const [, majorStr, minorStr, patchStr, prerelease, build] = strict;
+    return {
+      raw,
+      major: Number(majorStr),
+      minor: Number(minorStr),
+      patch: Number(patchStr),
+      prerelease: toIdentifiers(prerelease),
+      build: build ? build.split('.') : [],
+    };
+  }
+
+  const loose = LOOSE_VERSION_REGEX.exec(trimmed);
+  if (loose) {
+    const [, majorStr, minorStr, patchStr] = loose;
+    return {
+      raw,
+      major: Number(majorStr),
+      minor: minorStr !== undefined ? Number(minorStr) : 0,
+      patch: patchStr !== undefined ? Number(patchStr) : 0,
+      prerelease: [],
+      build: [],
+    };
+  }
+
+  throw new InvalidVersionFormatException({
+    message: `Cannot parse version: "${raw}" does not match a recognized SemVer format`,
+    metadata: { raw },
+  });
+}
+
+function comparePrerelease(
+  a: readonly (string | number)[],
+  b: readonly (string | number)[]
+): -1 | 0 | 1 {
+  if (a.length === 0 && b.length === 0) return 0;
+  if (a.length === 0) return 1; // no prerelease outranks any prerelease
+  if (b.length === 0) return -1;
+
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const ai = a[i];
+    const bi = b[i];
+    if (ai === undefined) return -1; // shorter set of identifiers = lower precedence
+    if (bi === undefined) return 1;
+    if (ai === bi) continue;
+
+    const aIsNumber = typeof ai === 'number';
+    const bIsNumber = typeof bi === 'number';
+    if (aIsNumber && bIsNumber) return ai < bi ? -1 : 1;
+    if (aIsNumber && !bIsNumber) return -1; // numeric identifiers always have lower precedence
+    if (!aIsNumber && bIsNumber) return 1;
+    return String(ai) < String(bi) ? -1 : 1;
+  }
+  return 0;
+}
+
+export function compareVersions(
+  a: ParsedVersion,
+  b: ParsedVersion
+): -1 | 0 | 1 {
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1;
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1;
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1;
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+function bumpUpperBound(
+  base: ParsedVersion,
+  kind: 'caret' | 'tilde'
+): ParsedVersion {
+  if (kind === 'tilde') {
+    return {
+      ...base,
+      minor: base.minor + 1,
+      patch: 0,
+      prerelease: [],
+      build: [],
+    };
+  }
+  if (base.major > 0) {
+    return {
+      ...base,
+      major: base.major + 1,
+      minor: 0,
+      patch: 0,
+      prerelease: [],
+      build: [],
+    };
+  }
+  if (base.minor > 0) {
+    return {
+      ...base,
+      minor: base.minor + 1,
+      patch: 0,
+      prerelease: [],
+      build: [],
+    };
+  }
+  return { ...base, patch: base.patch + 1, prerelease: [], build: [] };
+}
+
+function satisfiesClause(version: ParsedVersion, clause: string): boolean {
+  const caretMatch = /^\^(.+)$/.exec(clause);
+  const caretArg = caretMatch?.[1];
+  if (caretArg) {
+    const base = parseVersion(caretArg);
+    const upper = bumpUpperBound(base, 'caret');
+    return (
+      compareVersions(version, base) >= 0 && compareVersions(version, upper) < 0
+    );
+  }
+
+  const tildeMatch = /^~(.+)$/.exec(clause);
+  const tildeArg = tildeMatch?.[1];
+  if (tildeArg) {
+    const base = parseVersion(tildeArg);
+    const upper = bumpUpperBound(base, 'tilde');
+    return (
+      compareVersions(version, base) >= 0 && compareVersions(version, upper) < 0
+    );
+  }
+
+  const opMatch = /^(>=|<=|>|<|=)?(.+)$/.exec(clause);
+  const opArg = opMatch?.[2];
+  if (opArg) {
+    const operator = opMatch?.[1] ?? '=';
+    const target = parseVersion(opArg);
+    const cmp = compareVersions(version, target);
+    switch (operator) {
+      case '>=':
+        return cmp >= 0;
+      case '<=':
+        return cmp <= 0;
+      case '>':
+        return cmp > 0;
+      case '<':
+        return cmp < 0;
+      default:
+        return cmp === 0;
+    }
+  }
+
+  return false;
+}
+
+export function satisfiesRange(version: ParsedVersion, range: string): boolean {
+  const clauses = range.trim().split(/\s+/).filter(Boolean);
+  if (clauses.length === 0) return false;
+  return clauses.every((clause) => satisfiesClause(version, clause));
+}
+
+export class SemVerEngine implements IVersionComparator {
+  parse(raw: string): ParsedVersion {
+    return parseVersion(raw);
+  }
+
+  compare(a: ParsedVersion, b: ParsedVersion): -1 | 0 | 1 {
+    return compareVersions(a, b);
+  }
+
+  satisfies(version: ParsedVersion, range: string): boolean {
+    return satisfiesRange(version, range);
+  }
+}

package/src/domain/errors/VersionManagerException.ts

@@ -0,0 +1,166 @@
+export type VersionManagerErrorCode =
+  | 'VM-1001' // InvalidConfigException
+  | 'VM-1002' // NotInitializedException
+  | 'VM-1003' // NotReadyException
+  | 'VM-1004' // SchemaValidationException
+  | 'VM-1005' // BoundaryValidationException
+  | 'VM-1006' // SignatureVerificationException
+  | 'VM-1007' // ConfigSizeLimitExceededException
+  | 'VM-1008' // UntrustedKeyIdException
+  | 'VM-1009' // EnvironmentOverrideConflictException
+  | 'VM-2001' // RequestTimeoutException
+  | 'VM-2002' // RateLimitException
+  | 'VM-2003' // OfflineException
+  | 'VM-2004' // TlsHandshakeException
+  | 'VM-3001' // AppNotFoundException
+  | 'VM-3002' // StorePermissionException
+  | 'VM-3003' // UnsupportedStoreException
+  | 'VM-3004' // StoreResponseParseException
+  | 'VM-4001' // InvalidVersionFormatException
+  | 'VM-5001' // PolicyEvaluationException
+  | 'VM-6001' // CacheCorruptionException
+  | 'VM-6002' // CacheWriteException
+  | 'VM-7001' // PlatformBridgeException
+  | 'VM-9999'; // UnknownVersionManagerException
+
+export interface VersionManagerExceptionInit {
+  message: string;
+  cause?: unknown;
+  metadata?: Record<string, unknown>;
+  retryable?: boolean;
+}
+
+export abstract class VersionManagerException extends Error {
+  abstract readonly code: VersionManagerErrorCode;
+  readonly cause: unknown;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly retryable: boolean;
+  readonly timestamp: number;
+
+  constructor(init: VersionManagerExceptionInit) {
+    super(init.message);
+    this.name = new.target.name;
+    this.cause = init.cause;
+    this.metadata = Object.freeze({ ...init.metadata });
+    this.retryable = init.retryable ?? false;
+    this.timestamp = Date.now();
+  }
+}
+
+export class InvalidConfigException extends VersionManagerException {
+  readonly code = 'VM-1001' as const;
+}
+
+export class NotInitializedException extends VersionManagerException {
+  readonly code = 'VM-1002' as const;
+}
+
+export class NotReadyException extends VersionManagerException {
+  readonly code = 'VM-1003' as const;
+}
+
+export class SchemaValidationException extends VersionManagerException {
+  readonly code = 'VM-1004' as const;
+}
+
+export class BoundaryValidationException extends VersionManagerException {
+  readonly code = 'VM-1005' as const;
+}
+
+export class SignatureVerificationException extends VersionManagerException {
+  readonly code = 'VM-1006' as const;
+}
+
+export class ConfigSizeLimitExceededException extends VersionManagerException {
+  readonly code = 'VM-1007' as const;
+}
+
+export class UntrustedKeyIdException extends VersionManagerException {
+  readonly code = 'VM-1008' as const;
+}
+
+export class EnvironmentOverrideConflictException extends VersionManagerException {
+  readonly code = 'VM-1009' as const;
+}
+
+export abstract class NetworkException extends VersionManagerException {}
+
+export class RequestTimeoutException extends NetworkException {
+  readonly code = 'VM-2001' as const;
+  override readonly retryable = true;
+}
+
+export class RateLimitException extends NetworkException {
+  readonly code = 'VM-2002' as const;
+  override readonly retryable = true;
+}
+
+export class OfflineException extends NetworkException {
+  readonly code = 'VM-2003' as const;
+  override readonly retryable = true;
+}
+
+export class TlsHandshakeException extends NetworkException {
+  readonly code = 'VM-2004' as const;
+}
+
+export abstract class StoreProviderException extends VersionManagerException {}
+
+export class AppNotFoundException extends StoreProviderException {
+  readonly code = 'VM-3001' as const;
+}
+
+export class StorePermissionException extends StoreProviderException {
+  readonly code = 'VM-3002' as const;
+}
+
+export class UnsupportedStoreException extends StoreProviderException {
+  readonly code = 'VM-3003' as const;
+}
+
+export class StoreResponseParseException extends StoreProviderException {
+  readonly code = 'VM-3004' as const;
+}
+
+export class InvalidVersionFormatException extends VersionManagerException {
+  readonly code = 'VM-4001' as const;
+}
+
+export class PolicyEvaluationException extends VersionManagerException {
+  readonly code = 'VM-5001' as const;
+}
+
+export abstract class CacheException extends VersionManagerException {}
+
+export class CacheCorruptionException extends CacheException {
+  readonly code = 'VM-6001' as const;
+}
+
+export class CacheWriteException extends CacheException {
+  readonly code = 'VM-6002' as const;
+  override readonly retryable = true;
+}
+
+export class PlatformBridgeException extends VersionManagerException {
+  readonly code = 'VM-7001' as const;
+}
+
+export class UnknownVersionManagerException extends VersionManagerException {
+  readonly code = 'VM-9999' as const;
+}
+
+export function toVersionManagerException(
+  error: unknown
+): VersionManagerException {
+  if (error instanceof VersionManagerException) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new UnknownVersionManagerException({ message, cause: error });
+}
+
+export function isConfigTierException(
+  error: unknown
+): error is VersionManagerException {
+  return (
+    error instanceof VersionManagerException && error.code.startsWith('VM-1')
+  );
+}

package/src/domain/models/ActionPlan.ts

@@ -0,0 +1,17 @@
+import type { UpdateInfo } from './UpdateInfo';
+
+export const ActionType = {
+  NO_ACTION: 'NO_ACTION',
+  FORCE_UPDATE: 'FORCE_UPDATE',
+  SOFT_UPDATE: 'SOFT_UPDATE',
+  OPTIONAL_REMINDER: 'OPTIONAL_REMINDER',
+} as const;
+
+export type ActionType = (typeof ActionType)[keyof typeof ActionType];
+
+export interface ActionPlan {
+  readonly type: ActionType;
+  readonly updateInfo: UpdateInfo | null;
+  readonly reason: string;
+  readonly decidedAt: number;
+}

package/src/domain/models/ConfigDocument.ts

@@ -0,0 +1,97 @@
+import type { StoreLinksOptions } from './VersionManagerOptions';
+
+/** Doc 03 §1.1 — the loadable configuration document (payload of a SignedConfigEnvelope). */
+export interface VersionManagerConfigDocument {
+  readonly localVersionIdentifier?: string;
+  readonly remoteConfigUrl?: string;
+  readonly cache?: {
+    readonly ttlMs?: number;
+    readonly storage?: 'memory' | 'persistent';
+  };
+  readonly network?: {
+    readonly requestTimeoutMs?: number;
+    readonly retry?: {
+      readonly maxAttempts?: number;
+      readonly backoff?: 'fixed' | 'exponential-jitter';
+      readonly baseDelayMs?: number;
+    };
+  };
+  readonly alerts?: {
+    readonly forceUpdateBelow?: string;
+    readonly reminderDelayMs?: number;
+    readonly customUiHookIds?: readonly string[];
+  };
+  readonly stores?: StoreLinksOptions;
+  /**
+   * Only ever read from tier 4 (configure()) per §4.2 — a document cannot alter the
+   * rules used to verify documents. Present in the type for schema-shape completeness
+   * (an incoming document that includes it is structurally valid but this field is
+   * always ignored by the precedence merge — see ConfigResolutionPipeline).
+   */
+  readonly security?: {
+    readonly signatureAlgorithm?: 'ed25519' | 'hmac-sha256' | 'none';
+    readonly trustedKeyIds?: readonly string[];
+  };
+  readonly schemaVersion?: string;
+}
+
+export type SignatureAlgorithm = 'ed25519' | 'hmac-sha256' | 'none';
+
+/** Doc 03 §3.1 — envelope wrapping every local/remote config document. */
+export interface SignedConfigEnvelope {
+  readonly schemaVersion: string;
+  readonly payload: VersionManagerConfigDocument;
+  readonly signature: {
+    readonly algorithm: SignatureAlgorithm;
+    readonly keyId: string;
+    readonly value: string; // base64
+    readonly signedAt: string; // ISO 8601
+  };
+}
+
+/** Opaque raw bytes/JSON before schema validation has proven its shape. */
+export type RawConfigDocument = unknown;
+
+export interface ConfigLoadRequest {
+  readonly defaults: import('./VersionManagerOptions').VersionManagerOptions;
+}
+
+export interface FetchOptions {
+  readonly timeoutMs: number;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+export interface TrustedKeySet {
+  readonly algorithm: SignatureAlgorithm;
+  /**
+   * Trusted keyIds only — per doc 03 §3.4, actual key material (public keys / HMAC
+   * secrets) is embedded at build time on the native side (Info.plist/BuildConfig), not
+   * shipped through JS. JS only needs to confirm the envelope's keyId is one this app
+   * trusts, then hand the keyId to ICryptoProvider, which resolves it to key material
+   * natively.
+   */
+  readonly keys: ReadonlySet<string>;
+}
+
+export type ConfigTier = 'env' | 'remote' | 'local' | 'default';
+
+export interface SchemaValidationResult {
+  readonly valid: boolean;
+  readonly errors: readonly string[];
+}
+
+export interface BoundaryValidationResult {
+  readonly valid: boolean;
+  /** Field-path -> reason, so the pipeline can drop only the offending fields (§7.3). */
+  readonly fieldErrors: ReadonlyMap<string, string>;
+}
+
+export interface SignatureVerificationResult {
+  readonly valid: boolean;
+  readonly reason?: string;
+}
+
+export interface ResolvedConfigWithProvenance {
+  readonly config: import('./VersionManagerOptions').ResolvedVersionManagerConfig;
+  readonly tier: ConfigTier;
+}

package/src/domain/models/Events.ts

@@ -0,0 +1,48 @@
+import type { VersionManagerException } from '../errors/VersionManagerException';
+import type { ActionPlan } from './ActionPlan';
+import type { LifecycleState } from './LifecycleState';
+import type { UpdateInfo } from './UpdateInfo';
+
+export interface StateChangedEvent {
+  readonly from: LifecycleState;
+  readonly to: LifecycleState;
+  readonly timestamp: number;
+}
+
+export interface UpdateDetectedEvent {
+  readonly updateInfo: UpdateInfo;
+  readonly actionPlan: ActionPlan;
+  readonly timestamp: number;
+}
+
+export interface UpdateNotAvailableEvent {
+  readonly currentVersion: string;
+  readonly checkedAt: number;
+}
+
+export type UserActionType =
+  'update_clicked' | 'later_clicked' | 'ignore_clicked' | 'dismiss_clicked';
+
+export interface UserActionEvent {
+  readonly action: UserActionType;
+  readonly updateInfo: UpdateInfo;
+  readonly timestamp: number;
+}
+
+export type ErrorPhase = 'config' | 'check' | 'policy' | 'presentation';
+
+export interface VersionManagerErrorEvent {
+  readonly error: VersionManagerException;
+  readonly phase: ErrorPhase;
+  readonly timestamp: number;
+}
+
+export interface VersionManagerEventMap {
+  stateChanged: StateChangedEvent;
+  updateDetected: UpdateDetectedEvent;
+  updateNotAvailable: UpdateNotAvailableEvent;
+  userAction: UserActionEvent;
+  error: VersionManagerErrorEvent;
+}
+
+export type VersionManagerEventType = keyof VersionManagerEventMap;

package/src/domain/models/LifecycleState.ts

@@ -0,0 +1,50 @@
+export const LifecycleState = {
+  UNINITIALIZED: 'UNINITIALIZED',
+  CONFIG_LOADING: 'CONFIG_LOADING',
+  IDLE: 'IDLE',
+  VERSION_CHECKING: 'VERSION_CHECKING',
+  DECIDING: 'DECIDING',
+  FORCE_UPDATE_DISPLAYED: 'FORCE_UPDATE_DISPLAYED',
+  SOFT_UPDATE_DISPLAYED: 'SOFT_UPDATE_DISPLAYED',
+  REJECTED_WAITING_REMINDER: 'REJECTED_WAITING_REMINDER',
+  TERMINATED: 'TERMINATED',
+} as const;
+
+export type LifecycleState =
+  (typeof LifecycleState)[keyof typeof LifecycleState];
+
+/**
+ * Allowed transitions. Anything not listed here is invalid and
+ * ILifecycleStateMachine.transition() must reject it.
+ */
+export const LIFECYCLE_TRANSITIONS: Readonly<
+  Record<LifecycleState, readonly LifecycleState[]>
+> = {
+  UNINITIALIZED: [LifecycleState.CONFIG_LOADING],
+  CONFIG_LOADING: [LifecycleState.IDLE, LifecycleState.TERMINATED],
+  IDLE: [LifecycleState.VERSION_CHECKING, LifecycleState.TERMINATED],
+  VERSION_CHECKING: [
+    LifecycleState.DECIDING,
+    LifecycleState.IDLE,
+    LifecycleState.TERMINATED,
+  ],
+  DECIDING: [
+    LifecycleState.FORCE_UPDATE_DISPLAYED,
+    LifecycleState.SOFT_UPDATE_DISPLAYED,
+    LifecycleState.REJECTED_WAITING_REMINDER,
+    LifecycleState.IDLE,
+    LifecycleState.TERMINATED,
+  ],
+  FORCE_UPDATE_DISPLAYED: [LifecycleState.TERMINATED],
+  SOFT_UPDATE_DISPLAYED: [
+    LifecycleState.IDLE,
+    LifecycleState.REJECTED_WAITING_REMINDER,
+    LifecycleState.TERMINATED,
+  ],
+  REJECTED_WAITING_REMINDER: [
+    LifecycleState.IDLE,
+    LifecycleState.VERSION_CHECKING,
+    LifecycleState.TERMINATED,
+  ],
+  TERMINATED: [],
+};

package/src/domain/models/ParsedVersion.ts

@@ -0,0 +1,8 @@
+export interface ParsedVersion {
+  readonly raw: string;
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  readonly prerelease: readonly (string | number)[];
+  readonly build: readonly string[];
+}

package/src/domain/models/PlatformId.ts

@@ -0,0 +1,9 @@
+export type PlatformId = 'ios' | 'android' | 'web';
+
+export type StoreProviderId =
+  | 'apple'
+  | 'google-play'
+  | 'huawei'
+  | 'amazon'
+  | 'custom'
+  | 'firebase-remote-config';

package/src/domain/models/PublicApiOptions.ts

@@ -0,0 +1,14 @@
+export interface CheckForUpdatesOptions {
+  bypassCache?: boolean;
+  silent?: boolean;
+  timeoutMs?: number;
+  context?: Record<string, unknown>;
+}
+
+export interface ForceTriggerOptions {
+  reason?: string;
+}
+
+export interface ResetIgnoredVersionsOptions {
+  versions?: string[];
+}

package/src/domain/models/RemoteVersionInfo.ts

@@ -0,0 +1,23 @@
+import type { PlatformId, StoreProviderId } from './PlatformId';
+
+export interface RemoteVersionInfo {
+  readonly latestVersion: string;
+  readonly storeUrl: string;
+  readonly releaseNotes: string | null;
+  readonly minimumOsVersion: string | null;
+  readonly fetchedAt: number;
+  readonly provider: StoreProviderId;
+}
+
+export interface VersionCheckRequest {
+  readonly currentVersion: string;
+  readonly bundleId: string;
+  readonly platform: PlatformId;
+  readonly bypassCache: boolean;
+  readonly timeoutMs: number;
+}
+
+export interface UserVersionDecision {
+  readonly ignoredVersions: readonly string[];
+  readonly remindMeLaterUntil: number | null;
+}

package/src/domain/models/StoreLookup.ts

@@ -0,0 +1,12 @@
+export interface StoreLookupRequest {
+  readonly bundleId: string;
+  readonly region: string | null;
+  readonly timeoutMs: number;
+}
+
+export interface StoreLookupResult {
+  readonly latestVersion: string;
+  readonly storeUrl: string;
+  readonly releaseNotes: string | null;
+  readonly minimumOsVersion: string | null;
+}

package/src/domain/models/Unsubscribe.ts

@@ -0,0 +1 @@
+export type Unsubscribe = () => void;

package/src/domain/models/UpdateInfo.ts

@@ -0,0 +1,11 @@
+import type { StoreProviderId } from './PlatformId';
+
+export interface UpdateInfo {
+  readonly currentVersion: string;
+  readonly latestVersion: string;
+  readonly storeUrl: string;
+  readonly releaseNotes: string | null;
+  readonly isForceUpdate: boolean;
+  readonly provider: StoreProviderId;
+  readonly fetchedAt: number;
+}