From 1013a05b8327d81adb4d4936de0e8dab3103294b Mon Sep 17 00:00:00 2001
From: Emil Lerch <emil@lerch.org>
Date: Tue, 9 Dec 2025 12:06:46 -0800
Subject: [PATCH] ai added comments

---
 src/main.zig | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/main.zig b/src/main.zig
index db7f6d0..b2c1a30 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -8,11 +8,13 @@ const appsync_url = "https://s34ox7kri5dsvdr43bfgp6qh6i.appsync-api.us-east-1.am
 const api_key = "da2-dm2g4rqvjbaoxcpo4eccs3k5he";
 const shadow_api_url = "https://698suy4zs3.execute-api.us-east-1.amazonaws.com/Prod/thing";
 
+/// Authentication result containing ID token and user UUID
 const AuthResult = struct {
     id_token: []const u8,
     user_uuid: []const u8,
 };
 
+/// Credentials loaded from file with managed memory
 const CognitoCredentials = struct {
     allocator: std.mem.Allocator,
     buffer: []const u8,
@@ -26,6 +28,8 @@ const CognitoCredentials = struct {
         self.password = undefined;
     }
 };
+
+/// Reads username and password from .credentials file (one per line)
 fn readCredentials(allocator: std.mem.Allocator) !CognitoCredentials {
     // TODO: something different
     const file = try std.fs.cwd().openFile(".credentials", .{});
@@ -46,6 +50,7 @@ fn readCredentials(allocator: std.mem.Allocator) !CognitoCredentials {
     };
 }
 
+/// Authenticates with AWS Cognito and returns ID token and user UUID
 fn authenticate(allocator: std.mem.Allocator, username: []const u8, password: []const u8) !AuthResult {
     var client = http.Client{ .allocator = allocator };
     defer client.deinit();
@@ -97,6 +102,7 @@ fn authenticate(allocator: std.mem.Allocator, username: []const u8, password: []
     return .{ .id_token = id_token_copy, .user_uuid = user_uuid_copy };
 }
 
+/// Fetches device list from AppSync GraphQL API for the given user
 fn getDevices(allocator: std.mem.Allocator, id_token: []const u8, username: []const u8) !json.Parsed(json.Value) {
     var client = http.Client{ .allocator = allocator };
     defer client.deinit();
@@ -126,6 +132,7 @@ fn getDevices(allocator: std.mem.Allocator, id_token: []const u8, username: []co
     return try json.parseFromSlice(json.Value, allocator, response_body, .{});
 }
 
+/// Starts recirculation for the specified device with given duration
 fn startRecirculation(allocator: std.mem.Allocator, id_token: []const u8, serial_number: []const u8, duration_minutes: u32) !bool {
     var client = http.Client{ .allocator = allocator };
     defer client.deinit();
@@ -153,6 +160,7 @@ fn startRecirculation(allocator: std.mem.Allocator, id_token: []const u8, serial
     return result.status == .ok;
 }
 
+/// Queries the device shadow to get current recirculation status
 fn getRecirculationStatus(allocator: std.mem.Allocator, id_token: []const u8, serial_number: []const u8) !json.Parsed(json.Value) {
     var client = http.Client{ .allocator = allocator };
     defer client.deinit();