@codeimplants/version-control 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,344 @@
+# Version Control SDK
+
+A lightweight, backend-driven SDK that enables remote control of app version behavior including soft updates, force updates, and maintenance mode for mobile and web applications.
+
+## Features
+
+- 🚀 **Soft Updates** - Notify users about new versions with optional updates
+- ⚡ **Force Updates** - Enforce minimum version requirements
+- 🔧 **Maintenance Mode** - Put your app in maintenance mode remotely
+- 🛑 **Kill Switch** - Emergency app disable capability
+- 📱 **Cross-Platform** - Works on iOS, Android, and Web
+- 🎯 **Auto-Detection** - Automatically detects platform, version, and app ID
+- 🔌 **Backend-Driven** - All decisions made server-side for instant updates
+- 🪶 **Lightweight** - Minimal dependencies and footprint
+
+## Installation
+
+```bash
+npm install @codeimplants/version-control
+```
+
+Or with yarn:
+
+```bash
+yarn add @codeimplants/version-control
+```
+
+## Quick Start
+
+### Simple Usage
+
+```typescript
+import { VersionSDK } from "@codeimplants/version-control";
+
+// Quick check with minimal config
+const decision = await VersionSDK.check(
+  "https://api.yourapp.com",
+  "your-api-key",
+);
+
+// Handle the decision
+switch (decision.action) {
+  case "FORCE_UPDATE":
+    // Show force update dialog
+    window.location.href = decision.storeUrl;
+    break;
+  case "SOFT_UPDATE":
+    // Show optional update dialog
+    showUpdatePrompt(decision.message, decision.storeUrl);
+    break;
+  case "MAINTENANCE":
+    // Show maintenance screen
+    showMaintenanceScreen(decision.message);
+    break;
+  case "KILL_SWITCH":
+    // App is disabled
+    showKillSwitchScreen(decision.message);
+    break;
+  case "NONE":
+    // Continue normally
+    break;
+}
+```
+
+### Advanced Usage
+
+```typescript
+import { VersionSDK, VCConfig } from "@codeimplants/version-control";
+
+const config: VCConfig = {
+  backendUrl: "https://api.yourapp.com",
+  apiKey: "your-api-key",
+  appId: "com.yourapp.mobile", // Optional: auto-detected
+  platform: "ios", // Optional: auto-detected
+  version: "2.1.0", // Optional: auto-detected
+  timeout: 8000, // Optional: default 8000ms
+  debug: true, // Optional: enable logging
+};
+
+const sdk = VersionSDK.init(config);
+const decision = await sdk.checkVersion();
+```
+
+## Auto-Detection
+
+The SDK automatically detects the following if not provided:
+
+### Platform Detection
+
+- **Capacitor**: Detects iOS/Android via Capacitor.getPlatform()
+- **React Native**: Detects via navigator.product
+- **User Agent**: Falls back to UA string parsing
+- **Web**: Default fallback
+
+### Version Detection
+
+Checks in order:
+
+1. Capacitor App plugin (`Capacitor.Plugins.App.getInfo()`)
+2. Global variables: `APP_VERSION`, `__VERSION__`, `VERSION`, `packageVersion`
+3. Fallback: `"1.0.0"`
+
+### App ID Detection
+
+Checks in order:
+
+1. Capacitor App plugin bundle ID
+2. Global variables: `APP_ID`, `__APP_ID__`, `BUNDLE_ID`, `PACKAGE_NAME`
+3. Fallback: `"unknown.app"`
+
+## Configuration
+
+### VCConfig
+
+```typescript
+interface VCConfig {
+  backendUrl: string; // Your backend API URL (required)
+  apiKey?: string; // API key for authentication
+  appId?: string; // App identifier (auto-detected if not provided)
+  platform?: Platform; // 'android' | 'ios' | 'web' | 'all'
+  version?: string; // Current app version (auto-detected if not provided)
+  timeout?: number; // Request timeout in ms (default: 8000)
+  debug?: boolean; // Enable debug logging
+}
+```
+
+## Response Types
+
+### VCDecision
+
+```typescript
+interface VCDecision {
+  action: VCAction; // The action to take
+  message?: string; // User-facing message
+  storeUrl?: string; // App store URL for updates
+  minVersion?: string; // Minimum required version (for FORCE_UPDATE)
+  latestVersion?: string; // Latest available version
+  raw?: any; // Raw backend response
+}
+```
+
+### Actions
+
+- **`NONE`** - No action required, app is up to date
+- **`SOFT_UPDATE`** - Update available but optional
+- **`FORCE_UPDATE`** - Update required to continue
+- **`MAINTENANCE`** - App is in maintenance mode
+- **`KILL_SWITCH`** - App is disabled
+- **`BLOCKED`** - Access blocked for this version/platform
+
+## Backend Integration
+
+The SDK expects your backend endpoint to accept POST requests at `/sdk/version/check`:
+
+### Request Format
+
+```typescript
+{
+  "appId": "com.yourapp.mobile",
+  "platform": "ios",
+  "currentVersion": "2.0.0",
+  "environment": "prod"
+}
+```
+
+### Response Format
+
+```typescript
+{
+  "status": "FORCE_UPDATE",           // VCAction
+  "message": "Please update to continue",
+  "title": "Update Required",
+  "minVersion": "2.1.0",
+  "latestVersion": "2.3.0",
+  "storeUrl": "https://apps.apple.com/..."
+}
+```
+
+## Examples
+
+### React Example
+
+```typescript
+import React, { useEffect, useState } from 'react';
+import { VersionSDK, VCDecision } from '@codeimplants/version-control';
+
+function App() {
+  const [versionCheck, setVersionCheck] = useState<VCDecision | null>(null);
+
+  useEffect(() => {
+    async function checkVersion() {
+      const decision = await VersionSDK.check(
+        'https://api.yourapp.com',
+        'your-api-key'
+      );
+      setVersionCheck(decision);
+    }
+    checkVersion();
+  }, []);
+
+  if (versionCheck?.action === 'FORCE_UPDATE') {
+    return (
+      <div className="update-required">
+        <h1>Update Required</h1>
+        <p>{versionCheck.message}</p>
+        <button onClick={() => window.location.href = versionCheck.storeUrl}>
+          Update Now
+        </button>
+      </div>
+    );
+  }
+
+  if (versionCheck?.action === 'MAINTENANCE') {
+    return (
+      <div className="maintenance">
+        <h1>Maintenance Mode</h1>
+        <p>{versionCheck.message}</p>
+      </div>
+    );
+  }
+
+  return <YourApp />;
+}
+```
+
+### Capacitor/Ionic Example
+
+```typescript
+import { VersionSDK } from "@codeimplants/version-control";
+import { AlertController } from "@ionic/angular";
+
+export class AppComponent {
+  constructor(private alertController: AlertController) {}
+
+  async ngOnInit() {
+    const decision = await VersionSDK.check(
+      "https://api.yourapp.com",
+      "your-api-key",
+    );
+
+    if (decision.action === "SOFT_UPDATE") {
+      const alert = await this.alertController.create({
+        header: "Update Available",
+        message: decision.message,
+        buttons: [
+          { text: "Later", role: "cancel" },
+          {
+            text: "Update",
+            handler: () => {
+              window.open(decision.storeUrl, "_system");
+            },
+          },
+        ],
+      });
+      await alert.present();
+    }
+  }
+}
+```
+
+### React Native Example
+
+```typescript
+import { VersionSDK } from "@codeimplants/version-control";
+import { Alert, Linking } from "react-native";
+
+async function checkAppVersion() {
+  const decision = await VersionSDK.check(
+    "https://api.yourapp.com",
+    "your-api-key",
+  );
+
+  if (decision.action === "FORCE_UPDATE") {
+    Alert.alert(
+      "Update Required",
+      decision.message,
+      [
+        {
+          text: "Update Now",
+          onPress: () => Linking.openURL(decision.storeUrl),
+        },
+      ],
+      { cancelable: false },
+    );
+  }
+}
+```
+
+## Version Comparison
+
+The SDK uses semantic versioning (semver) comparison:
+
+```typescript
+// Examples of version comparisons
+"1.0.0" < "1.0.1"; // true
+"1.0.0" < "1.1.0"; // true
+"2.0.0" > "1.9.9"; // true
+"1.0" === "1.0.0"; // true (normalized)
+```
+
+## Error Handling
+
+The SDK gracefully handles errors and returns `{ action: "NONE" }` if:
+
+- Network request fails
+- Backend is unreachable
+- Request times out
+- Invalid response format
+
+Enable debug mode to see detailed error logs:
+
+```typescript
+const config = {
+  backendUrl: "https://api.yourapp.com",
+  debug: true, // Logs all requests and responses
+};
+```
+
+## Best Practices
+
+1. **Check on App Launch** - Always check version status when the app starts
+2. **Cache Decisions** - Cache the decision for a reasonable time (e.g., 1 hour)
+3. **Handle Offline** - Gracefully handle offline scenarios (SDK returns `NONE`)
+4. **User Experience** - Don't interrupt critical user flows with update prompts
+5. **Test Thoroughly** - Test all action types before deploying rules
+6. **Gradual Rollouts** - Use backend rules to gradually roll out forced updates
+
+## Platform Support
+
+- ✅ iOS (Native & Web)
+- ✅ Android (Native & Web)
+- ✅ Web Browsers
+- ✅ Capacitor
+- ✅ React Native
+- ✅ Ionic
+- ✅ Cordova
+
+## TypeScript
+
+The SDK is written in TypeScript and includes full type definitions.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@codeimplants/version-control",
-  "version": "1.0.0",
+  "version": "1.0.2",
+  "description": "A lightweight cross-platform SDK to remotely control app version behavior such as soft update, force update, and maintenance mode using backend-driven rules, without enforcing UI.",
+  "keywords": [
+    "version-control",
+    "app-version",
+    "mobile-versioning",
+    "force-update",
+    "soft-update",
+    "maintenance-mode",
+    "capacitor",
+    "ionic",
+    "react-native",
+    "react",
+    "angular",
+    "android",
+    "ios",
+    "mobile-sdk",
+    "update-management",
+    "feature-control",
+    "remote-config",
+    "sdk"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/.turbo/cache/27fad7e4fc35ffd5-meta.json

@@ -1 +0,0 @@
-{"hash":"27fad7e4fc35ffd5","duration":4627}

package/.turbo/cache/3a784e60ef4fd5a6-meta.json

@@ -1 +0,0 @@
-{"hash":"3a784e60ef4fd5a6","duration":1325}

package/.turbo/cache/5ff842ce2cdfa953-meta.json

@@ -1 +0,0 @@
-{"hash":"5ff842ce2cdfa953","duration":1270}

package/.turbo/cache/60a231c552bcee53-meta.json

@@ -1 +0,0 @@
-{"hash":"60a231c552bcee53","duration":2326}

package/.turbo/cache/6c7d12bf8eda1401-meta.json

@@ -1 +0,0 @@
-{"hash":"6c7d12bf8eda1401","duration":1164}

package/.turbo/cache/b1169bf3a222dd96-meta.json

@@ -1 +0,0 @@
-{"hash":"b1169bf3a222dd96","duration":2680}

package/.turbo/cache/bef44a5355c4c0bf-meta.json

@@ -1 +0,0 @@
-{"hash":"bef44a5355c4c0bf","duration":2233}

package/.turbo/daemon/16cf72aee83bd4e9-turbo.log.2026-01-29

@@ -1 +0,0 @@
-2026-01-29T08:29:08.349183Z  WARN daemon_server: turborepo_lib::commands::daemon: daemon already running

package/.turbo/daemon/16cf72aee83bd4e9-turbo.log.2026-01-30

@@ -1,2 +0,0 @@
-2026-01-30T13:27:33.409085Z  WARN daemon_server: turborepo_lib::commands::daemon: daemon already running
-2026-01-30T19:18:48.539522Z  WARN daemon_server: turborepo_lib::commands::daemon: daemon already running