feat: implement manual update check JSON contract

hemanandr · claude · hemanandr · commit ce4cb248ef58 · 2025-08-25T11:16:24.000+05:30
- Update docs/updates.md with static JSON contract specification * Simple {current, latest, notes_url} format for offline-safe updates * Complete JSON schema with SemVer validation patterns * Implementation examples for manual update checking * Hosting recommendations (GitHub Pages, CDN, static sites) - Add sample update check JSON files in ops/examples/ * updates.json - standard update available scenario * updates-beta.json - pre-release version example * updates-no-update.json - up-to-date scenario * README.md with usage instructions and automation tips - Update OpenAPI specification (docs/openapi.yaml) * Revised /api/updates/latest endpoint to use UpdateCheck schema * Simplified response format aligned with static JSON contract * Updated examples to reflect new {current, latest, notes_url} format Addresses ENV-16 requirements for manual-only update checking with static JSON contract for offline-safe deployments. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
@@ -547,37 +547,34 @@ paths:
   # Update Management
   /api/updates/latest:
     get:
-      summary: Check for software updates
+      summary: Get update check information
       description: >
-        Checks for available software updates by comparing current version with
-        latest release. Manual update checking only - no automatic updates.
-      operationId: checkUpdates
+        Returns static update check information following the manual update JSON contract.
+        Contains current version, latest available version, and release notes URL.
+        Manual checking only - no automatic updates or downloads.
+      operationId: getUpdateInfo
       tags:
         - Updates
       responses:
         "200":
-          description: Update information retrieved successfully
+          description: Update check information retrieved successfully
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/UpdateInfo"
+                $ref: "#/components/schemas/UpdateCheck"
               examples:
                 update_available:
                   summary: Update available
                   value:
-                    current_version: "0.1.0"
-                    latest_version: "0.2.0"
-                    update_available: true
-                    release_notes_url: "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v0.2.0"
-                    download_url: "https://github.com/MachDatum/ThingConnect.Pulse/releases/download/v0.2.0/ThingConnect.Pulse.Setup.exe"
+                    current: "1.0.0"
+                    latest: "1.2.1"
+                    notes_url: "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v1.2.1"
                 up_to_date:
                   summary: Current version is latest
                   value:
-                    current_version: "0.1.0"
-                    latest_version: "0.1.0"
-                    update_available: false
-                    release_notes_url: null
-                    download_url: null
+                    current: "1.2.1"
+                    latest: "1.2.1"
+                    notes_url: "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v1.2.1"
         "500":
           $ref: "#/components/responses/InternalError"
 
@@ -1069,40 +1066,29 @@ components:
         - errors
 
     # Update Management
-    UpdateInfo:
+    UpdateCheck:
       type: object
-      description: Software update information
+      description: Update check JSON contract for manual update checking
       properties:
-        current_version:
+        current:
           type: string
-          pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?$"
-          description: Current installed version (SemVer)
-          example: "0.1.0"
-        latest_version:
+          pattern: "^\\d+\\.\\d+\\.\\d+(-.+)?$"
+          description: Current installed version in SemVer format
+          example: "1.0.0"
+        latest:
           type: string
-          pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?$"
-          description: Latest available version (SemVer)
-          example: "0.2.0"
-        update_available:
-          type: boolean
-          description: Whether an update is available
-          example: true
-        release_notes_url:
-          type: string
-          format: uri
-          nullable: true
-          description: URL to release notes for latest version
-          example: "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v0.2.0"
-        download_url:
+          pattern: "^\\d+\\.\\d+\\.\\d+(-.+)?$"
+          description: Latest available version in SemVer format
+          example: "1.2.1"
+        notes_url:
           type: string
           format: uri
-          nullable: true
-          description: URL to download latest version installer
-          example: "https://github.com/MachDatum/ThingConnect.Pulse/releases/download/v0.2.0/ThingConnect.Pulse.Setup.exe"
+          description: URL to release notes for the latest version
+          example: "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v1.2.1"
       required:
-        - current_version
-        - latest_version
-        - update_available
+        - current
+        - latest
+        - notes_url
 
     # Error Response
     ErrorResponse:
diff --git a/docs/updates.md b/docs/updates.md
@@ -63,50 +63,103 @@ graph TD
 
 ## Update Detection & Notification
 
-### GitHub Release Integration
+### Manual Update Check JSON Contract
 
-**Release API Endpoint**:
+ThingConnect Pulse uses a **static JSON contract** for manual update checks, designed to be offline-safe and simple to implement.
+
+**Update Check JSON Schema**:
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ThingConnect Pulse Update Check",
+  "type": "object",
+  "required": ["current", "latest", "notes_url"],
+  "properties": {
+    "current": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-.+)?$",
+      "description": "Current application version in SemVer format"
+    },
+    "latest": {
+      "type": "string", 
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-.+)?$",
+      "description": "Latest available version in SemVer format"
+    },
+    "notes_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to release notes for the latest version"
+    }
+  }
+}
 ```
-GET https://api.github.com/repos/MachDatum/ThingConnect.Pulse/releases/latest
+
+**Example Update Check Response**:
+```json
+{
+  "current": "1.0.0",
+  "latest": "1.2.1", 
+  "notes_url": "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v1.2.1"
+}
 ```
 
-**Response Processing**:
+### Update Check Implementation
+
+**Manual Update Check Service**:
 ```csharp
 public sealed class UpdateService : IUpdateService
 {
-    public async Task<UpdateInfo> CheckForUpdatesAsync()
+    private readonly HttpClient _httpClient;
+    private readonly ILogger<UpdateService> _logger;
+    
+    public async Task<UpdateInfo> CheckForUpdatesAsync(string updateJsonUrl)
     {
         try
         {
-            using var client = new HttpClient();
-            client.DefaultRequestHeaders.Add("User-Agent", "ThingConnect.Pulse/1.0.0");
+            _httpClient.DefaultRequestHeaders.Add("User-Agent", "ThingConnect.Pulse/1.0.0");
             
-            var response = await client.GetStringAsync(
-                "https://api.github.com/repos/MachDatum/ThingConnect.Pulse/releases/latest");
-            var release = JsonSerializer.Deserialize<GitHubRelease>(response);
+            var response = await _httpClient.GetStringAsync(updateJsonUrl);
+            var updateCheck = JsonSerializer.Deserialize<UpdateCheckResponse>(response);
             
-            var latestVersion = Version.Parse(release.TagName.TrimStart('v'));
-            var currentVersion = Assembly.GetExecutingAssembly().GetName().Version;
+            var latestVersion = Version.Parse(updateCheck.Latest);
+            var currentVersion = Version.Parse(updateCheck.Current);
             
             return new UpdateInfo
             {
                 HasUpdate = latestVersion > currentVersion,
                 LatestVersion = latestVersion,
                 CurrentVersion = currentVersion,
-                ReleaseNotes = release.Body,
-                DownloadUrl = release.Assets.FirstOrDefault()?.BrowserDownloadUrl,
-                PublishedAt = release.PublishedAt
+                NotesUrl = updateCheck.NotesUrl,
+                UpdateAvailable = latestVersion > currentVersion
             };
         }
         catch (Exception ex)
         {
-            _logger.LogWarning(ex, "Failed to check for updates");
+            _logger.LogWarning(ex, "Failed to check for updates from {Url}", updateJsonUrl);
             return UpdateInfo.CheckFailed();
         }
     }
 }
+
+public record UpdateCheckResponse(
+    string Current,
+    string Latest, 
+    string NotesUrl
+);
 ```
 
+### Static JSON Hosting
+
+**GitHub Pages Hosting** (Recommended):
+- Host `updates.json` in the repository's `gh-pages` branch
+- Accessible via: `https://machDatum.github.io/ThingConnect.Pulse/updates.json`
+- Automatically updated via GitHub Actions on new releases
+
+**Alternative Hosting Options**:
+- **CDN**: CloudFlare, AWS CloudFront, or Azure CDN for global distribution
+- **Static hosting**: Netlify, Vercel, or similar services
+- **Enterprise**: Internal web servers for air-gapped environments
+
 ### Update Check Configuration
 
 **Settings Options**:
diff --git a/ops/examples/README.md b/ops/examples/README.md
@@ -0,0 +1,56 @@
+# Example Files
+
+This directory contains example files for ThingConnect Pulse operations and configuration.
+
+## Update Check JSON Examples
+
+### updates.json
+Standard update check response showing an available update from version 1.0.0 to 1.2.1.
+
+**Usage**: Host this file on a web server and configure ThingConnect Pulse to check this URL for updates.
+
+### updates-beta.json  
+Beta channel update check response showing a pre-release version (1.3.0-beta.2) available.
+
+**Usage**: Used for testing beta releases and pre-release update notifications.
+
+### updates-no-update.json
+Response when no update is available (current version matches latest version).
+
+**Usage**: Shows the expected format when the system is up-to-date.
+
+## Update Check JSON Contract
+
+All update check JSON files must follow this structure:
+
+```json
+{
+  "current": "1.0.0",           // Current installed version (SemVer)
+  "latest": "1.2.1",            // Latest available version (SemVer)  
+  "notes_url": "https://..."    // URL to release notes/changelog
+}
+```
+
+### Field Requirements
+
+- **current**: Must be a valid semantic version (MAJOR.MINOR.PATCH)
+- **latest**: Must be a valid semantic version, may include pre-release identifiers  
+- **notes_url**: Must be a valid HTTP/HTTPS URL pointing to release documentation
+
+### Hosting Recommendations
+
+1. **GitHub Pages**: Host in `gh-pages` branch for automatic updates
+2. **CDN**: Use CloudFlare or AWS CloudFront for global distribution
+3. **Static Site**: Deploy to Netlify, Vercel, or similar services
+4. **Enterprise**: Internal web servers for air-gapped environments
+
+### Automation
+
+Consider automating the update of these JSON files when new releases are published:
+
+```yaml
+# GitHub Actions example
+- name: Update JSON files
+  run: |
+    echo '{"current":"${{ env.PREVIOUS_VERSION }}","latest":"${{ env.NEW_VERSION }}","notes_url":"${{ env.RELEASE_URL }}"}' > updates.json
+```
diff --git a/ops/examples/updates-beta.json b/ops/examples/updates-beta.json
@@ -0,0 +1,5 @@
+{
+  "current": "1.0.0",
+  "latest": "1.3.0-beta.2",
+  "notes_url": "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v1.3.0-beta.2"
+}
diff --git a/ops/examples/updates-no-update.json b/ops/examples/updates-no-update.json
@@ -0,0 +1,5 @@
+{
+  "current": "1.2.1",
+  "latest": "1.2.1",
+  "notes_url": "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v1.2.1"
+}
diff --git a/ops/examples/updates.json b/ops/examples/updates.json
@@ -0,0 +1,5 @@
+{
+  "current": "1.0.0",
+  "latest": "1.2.1",
+  "notes_url": "https://github.com/MachDatum/ThingConnect.Pulse/releases/tag/v1.2.1"
+}
