refactor(network): restructure sync JSON return format with nested send/receive keys

Change the flat JSON return format of network functions to a nested
structure with "send" and "receive" top-level keys, rename
"rowsReceived" to "rows" for conciseness, and add a "tables" array
field to the receive section listing affected table names.

Before: {"status":"synced","localVersion":5,"serverVersion":5,"rowsReceived":3}
After:  {"send":{"status":"synced","localVersion":5,"serverVersion":5},"receive":{"rows":3,"tables":["tasks"]}}

Update integration tests to use SQLite's ->> operator for JSON field
extraction, and add db_expect_str helper for string assertions.

Author: andinux

.claude/commands/test-sync-roundtrip-postgres-local.md

@@ -115,7 +115,7 @@ SELECT cloudsync_network_send_changes();
 
 -- Check for changes from server (repeat with 2-3 second delays)
 SELECT cloudsync_network_check_changes();
--- Repeat check_changes 3-5 times with delays until it returns > 0 or stabilizes
+-- Repeat check_changes 3-5 times with delays until it returns more than 0 received rows or stabilizes
 
 -- Verify final data
 SELECT * FROM <table_name>;

.claude/commands/test-sync-roundtrip-sqlitecloud-rls.md

@@ -245,7 +245,7 @@ SELECT cloudsync_network_send_changes();
 
 -- Check for changes from server (repeat with 2-3 second delays)
 SELECT cloudsync_network_check_changes();
--- Repeat check_changes 3-5 times with delays until it returns 0 or stabilizes
+-- Repeat check_changes 3-5 times with delays until it returns more than 0 received rows or stabilizes
 ```
 
 **Recommended sync order:**

API.md

@@ -363,21 +363,21 @@ SELECT cloudsync_network_set_apikey('your_api_key');
 
 **Parameters:** None.
 
-**Returns:** A JSON string with the sync status:
+**Returns:** A JSON string with the send result:
 
 ```json
-{"status":"synced|syncing|out-of-sync|error", "localVersion": N, "serverVersion": N}
+{"send": {"status": "synced|syncing|out-of-sync|error", "localVersion": N, "serverVersion": N}}
 ```
 
-- `status`: The current sync state — `"synced"` (all changes confirmed), `"syncing"` (changes sent but not yet confirmed), `"out-of-sync"` (local changes pending or gaps detected), or `"error"`.
-- `localVersion`: The latest local database version.
-- `serverVersion`: The latest version confirmed by the server.
+- `send.status`: The current sync state — `"synced"` (all changes confirmed), `"syncing"` (changes sent but not yet confirmed), `"out-of-sync"` (local changes pending or gaps detected), or `"error"`.
+- `send.localVersion`: The latest local database version.
+- `send.serverVersion`: The latest version confirmed by the server.
 
 **Example:**
 
 ```sql
 SELECT cloudsync_network_send_changes();
--- '{"status":"synced","localVersion":5,"serverVersion":5}'
+-- '{"send":{"status":"synced","localVersion":5,"serverVersion":5}}'
 ```
 
 ---
@@ -395,19 +395,20 @@ If the network is misconfigured or the remote server is unreachable, the functio
 
 **Parameters:** None.
 
-**Returns:** A JSON string with the number of changes applied:
+**Returns:** A JSON string with the receive result:
 
 ```json
-{"rowsReceived": N}
+{"receive": {"rows": N, "tables": ["table1", "table2"]}}
 ```
 
-- `rowsReceived`: The number of rows downloaded and applied to the local database.
+- `receive.rows`: The number of rows received and applied to the local database.
+- `receive.tables`: An array of table names that received changes. Empty (`[]`) if no changes were applied.
 
 **Example:**
 
 ```sql
 SELECT cloudsync_network_check_changes();
--- '{"rowsReceived":3}'
+-- '{"receive":{"rows":3,"tables":["tasks"]}}'
 ```
 
 ---
@@ -424,23 +425,27 @@ SELECT cloudsync_network_check_changes();
 - `wait_ms` (INTEGER, optional): The time to wait in milliseconds between retries. Defaults to 100.
 - `max_retries` (INTEGER, optional): The maximum number of times to retry the synchronization. Defaults to 1.
 
-**Returns:** A JSON string with the full sync result:
+**Returns:** A JSON string with the full sync result, combining send and receive:
 
 ```json
-{"status":"synced|syncing|out-of-sync|error", "localVersion": N, "serverVersion": N, "rowsReceived": N}
+{
+  "send": {"status": "synced|syncing|out-of-sync|error", "localVersion": N, "serverVersion": N},
+  "receive": {"rows": N, "tables": ["table1", "table2"]}
+}
 ```
 
-- `status`: The current sync state — `"synced"`, `"syncing"`, `"out-of-sync"`, or `"error"`.
-- `localVersion`: The latest local database version.
-- `serverVersion`: The latest version confirmed by the server.
-- `rowsReceived`: The number of rows downloaded and applied during the check phase.
+- `send.status`: The current sync state — `"synced"`, `"syncing"`, `"out-of-sync"`, or `"error"`.
+- `send.localVersion`: The latest local database version.
+- `send.serverVersion`: The latest version confirmed by the server.
+- `receive.rows`: The number of rows received and applied during the check phase.
+- `receive.tables`: An array of table names that received changes. Empty (`[]`) if no changes were applied.
 
 **Example:**
 
 ```sql
 -- Perform a single synchronization cycle
 SELECT cloudsync_network_sync();
--- '{"status":"synced","localVersion":5,"serverVersion":5,"rowsReceived":3}'
+-- '{"send":{"status":"synced","localVersion":5,"serverVersion":5},"receive":{"rows":3,"tables":["tasks"]}}'
 
 -- Perform a synchronization cycle with custom retry settings
 SELECT cloudsync_network_sync(500, 3);

README.md

@@ -296,7 +296,7 @@ SELECT cloudsync_network_set_apikey('your-api-key-here');
 -- and, if a package with changes is ready to be downloaded, applies them to the local database
 SELECT cloudsync_network_sync();
 -- Returns a JSON string with sync status, e.g.:
--- '{"status":"synced","localVersion":5,"serverVersion":5,"rowsReceived":3}'
+-- '{"send":{"status":"synced","localVersion":5,"serverVersion":5},"receive":{"rows":3,"tables":["my_data"]}}'
 -- Keep calling periodically. In production applications, you would typically
 -- call this periodically rather than manually (e.g., every few seconds)
 SELECT cloudsync_network_sync();
@@ -325,7 +325,7 @@ SELECT cloudsync_network_set_apikey('your-api-key-here');
 
 -- Sync to get data from the first device
 SELECT cloudsync_network_sync();
--- Repeat — check rowsReceived in the JSON result to see if data was received
+-- Repeat — check receive.rows in the JSON result to see if data was received
 SELECT cloudsync_network_sync();
 
 -- View synchronized data

examples/simple-todo-db/README.md

@@ -168,7 +168,7 @@ SELECT cloudsync_network_set_apikey('your-api-key-here');
 
 -- Pull data from Device A - repeat until data is received
 SELECT cloudsync_network_sync();
--- Check the "rowsReceived" field in the JSON result to see if data was received
+-- Check "receive.rows" in the JSON result to see if data was received
 SELECT cloudsync_network_sync();
 
 -- Verify data was synced
@@ -199,7 +199,7 @@ SELECT cloudsync_network_sync();
 ```sql
 -- Get updates from Device B - repeat until data is received
 SELECT cloudsync_network_sync();
--- Check the "rowsReceived" field in the JSON result to see if data was received
+-- Check "receive.rows" in the JSON result to see if data was received
 SELECT cloudsync_network_sync();
 
 -- View all tasks (should now include Device B's additions)
@@ -232,7 +232,7 @@ SELECT cloudsync_network_has_unsent_changes();
 -- When network returns, sync automatically resolves conflicts
 -- Repeat until all changes are synchronized
 SELECT cloudsync_network_sync();
--- Check the "rowsReceived" field in the JSON result to see if data was received/sent
+-- Check "receive.rows" and "send.status" in the JSON result
 SELECT cloudsync_network_sync();
 ```
 

examples/to-do-app/components/SyncContext.js

@@ -60,9 +60,9 @@ export const SyncProvider = ({ children }) => {
 
           const raw = result.rows?.[0]?.['cloudsync_network_check_changes()'];
           if (raw) {
-            const { rowsReceived } = JSON.parse(raw);
-            if (rowsReceived > 0) {
-              console.log(`${rowsReceived} changes detected, triggering refresh`);
+            const { receive } = JSON.parse(raw);
+            if (receive.rows > 0) {
+              console.log(`${receive.rows} changes detected in [${receive.tables}], triggering refresh`);
               // Defer refresh to next tick to avoid blocking current interaction
               setTimeout(() => triggerRefresh(), 0);
             }

src/network.c

@@ -860,13 +860,33 @@ void cloudsync_network_set_apikey (sqlite3_context *context, int argc, sqlite3_v
     (result) ? sqlite3_result_int(context, SQLITE_OK) : sqlite3_result_error_code(context, SQLITE_NOMEM);
 }
 
+// Returns a malloc'd JSON array string like '["tasks","users"]', or NULL on error/no results.
+// Caller must free with cloudsync_memory_free.
+static char *network_get_affected_tables(sqlite3 *db, int64_t since_db_version) {
+    sqlite3_stmt *stmt = NULL;
+    int rc = sqlite3_prepare_v2(db,
+        "SELECT json_group_array(DISTINCT tbl) FROM cloudsync_changes WHERE db_version > ?",
+        -1, &stmt, NULL);
+    if (rc != SQLITE_OK) return NULL;
+    sqlite3_bind_int64(stmt, 1, since_db_version);
+
+    char *result = NULL;
+    if (sqlite3_step(stmt) == SQLITE_ROW) {
+        const char *json = (const char *)sqlite3_column_text(stmt, 0);
+        if (json) result = cloudsync_string_dup(json);
+    }
+    sqlite3_finalize(stmt);
+    return result;
+}
+
 // MARK: - Sync result
 
 typedef struct {
     int64_t     server_version;   // lastOptimisticVersion
     int64_t     local_version;    // new_db_version (max local)
     const char  *status;          // computed status string
     int         rows_received;    // rows from check
+    char        *tables_json;     // JSON array of affected table names, caller must cloudsync_memory_free
 } sync_result;
 
 static const char *network_compute_status(int64_t last_optimistic, int64_t last_confirmed,
@@ -1022,13 +1042,13 @@ int cloudsync_network_send_changes_internal (sqlite3_context *context, int argc,
 void cloudsync_network_send_changes (sqlite3_context *context, int argc, sqlite3_value **argv) {
     DEBUG_FUNCTION("cloudsync_network_send_changes");
 
-    sync_result sr = {-1, 0, NULL, 0};
+    sync_result sr = {-1, 0, NULL, 0, NULL};
     int rc = cloudsync_network_send_changes_internal(context, argc, argv, &sr);
     if (rc != SQLITE_OK) return;
 
     char buf[256];
     snprintf(buf, sizeof(buf),
-        "{\"status\":\"%s\",\"localVersion\":%" PRId64 ",\"serverVersion\":%" PRId64 "}",
+        "{\"send\":{\"status\":\"%s\",\"localVersion\":%" PRId64 ",\"serverVersion\":%" PRId64 "}}",
         sr.status ? sr.status : "error", sr.local_version, sr.server_version);
     sqlite3_result_text(context, buf, -1, SQLITE_TRANSIENT);
 }
@@ -1044,6 +1064,9 @@ int cloudsync_network_check_internal(sqlite3_context *context, int *pnrows, sync
     int seq = dbutils_settings_get_int_value(data, CLOUDSYNC_KEY_CHECK_SEQ);
     if (seq<0) {sqlite3_result_error(context, "Unable to retrieve seq.", -1); return -1;}
 
+    // Capture local db_version before download so we can query cloudsync_changes afterwards
+    int64_t prev_dbv = cloudsync_dbversion(data);
+
     char json_payload[2024];
     snprintf(json_payload, sizeof(json_payload), "{\"dbVersion\":%lld, \"seq\":%d}", (long long)db_version, seq);
 
@@ -1065,30 +1088,39 @@ int cloudsync_network_check_internal(sqlite3_context *context, int *pnrows, sync
 
     if (out && pnrows) out->rows_received = *pnrows;
 
+    // Query cloudsync_changes for affected tables after successful download
+    if (out && rc == SQLITE_OK && pnrows && *pnrows > 0) {
+        sqlite3 *db = (sqlite3 *)cloudsync_db(data);
+        out->tables_json = network_get_affected_tables(db, prev_dbv);
+    }
+
     network_result_cleanup(&result);
     return rc;
 }
 
 void cloudsync_network_sync (sqlite3_context *context, int wait_ms, int max_retries) {
-    sync_result sr = {-1, 0, NULL, 0};
+    sync_result sr = {-1, 0, NULL, 0, NULL};
     int rc = cloudsync_network_send_changes_internal(context, 0, NULL, &sr);
     if (rc != SQLITE_OK) return;
 
     int ntries = 0;
     int nrows = 0;
     while (ntries < max_retries) {
         if (ntries > 0) sqlite3_sleep(wait_ms);
+        if (sr.tables_json) { cloudsync_memory_free(sr.tables_json); sr.tables_json = NULL; }
         rc = cloudsync_network_check_internal(context, &nrows, &sr);
         if (rc == SQLITE_OK && nrows > 0) break;
         ntries++;
     }
-    if (rc != SQLITE_OK) return;
-
-    char buf[256];
-    snprintf(buf, sizeof(buf),
-        "{\"status\":\"%s\",\"localVersion\":%" PRId64 ",\"serverVersion\":%" PRId64 ",\"rowsReceived\":%d}",
-        sr.status ? sr.status : "error", sr.local_version, sr.server_version, nrows);
-    sqlite3_result_text(context, buf, -1, SQLITE_TRANSIENT);
+    if (rc != SQLITE_OK) { if (sr.tables_json) cloudsync_memory_free(sr.tables_json); return; }
+
+    const char *tables = sr.tables_json ? sr.tables_json : "[]";
+    char *buf = cloudsync_memory_mprintf(
+        "{\"send\":{\"status\":\"%s\",\"localVersion\":%" PRId64 ",\"serverVersion\":%" PRId64 "},"
+        "\"receive\":{\"rows\":%d,\"tables\":%s}}",
+        sr.status ? sr.status : "error", sr.local_version, sr.server_version, nrows, tables);
+    sqlite3_result_text(context, buf, -1, cloudsync_memory_free);
+    if (sr.tables_json) cloudsync_memory_free(sr.tables_json);
 }
 
 void cloudsync_network_sync0 (sqlite3_context *context, int argc, sqlite3_value **argv) {
@@ -1111,13 +1143,15 @@ void cloudsync_network_sync2 (sqlite3_context *context, int argc, sqlite3_value
 void cloudsync_network_check_changes (sqlite3_context *context, int argc, sqlite3_value **argv) {
     DEBUG_FUNCTION("cloudsync_network_check_changes");
 
+    sync_result sr = {-1, 0, NULL, 0, NULL};
     int nrows = 0;
-    int rc = cloudsync_network_check_internal(context, &nrows, NULL);
-    if (rc != SQLITE_OK) return;
+    int rc = cloudsync_network_check_internal(context, &nrows, &sr);
+    if (rc != SQLITE_OK) { if (sr.tables_json) cloudsync_memory_free(sr.tables_json); return; }
 
-    char buf[128];
-    snprintf(buf, sizeof(buf), "{\"rowsReceived\":%d}", nrows);
-    sqlite3_result_text(context, buf, -1, SQLITE_TRANSIENT);
+    const char *tables = sr.tables_json ? sr.tables_json : "[]";
+    char *buf = cloudsync_memory_mprintf("{\"receive\":{\"rows\":%d,\"tables\":%s}}", nrows, tables);
+    sqlite3_result_text(context, buf, -1, cloudsync_memory_free);
+    if (sr.tables_json) cloudsync_memory_free(sr.tables_json);
 }
 
 void cloudsync_network_reset_sync_version (sqlite3_context *context, int argc, sqlite3_value **argv) {

test/integration.c

@@ -41,7 +41,7 @@
 #define TERMINATE       if (db) { db_exec(db, "SELECT cloudsync_terminate();"); }
 #define ABORT_TEST      abort_test: ERROR_MSG TERMINATE if (db) sqlite3_close(db); return rc;
 
-typedef enum { PRINT, NOPRINT, INTGR, GT0 } expected_type;
+typedef enum { PRINT, NOPRINT, INTGR, GT0, STR } expected_type;
 
 typedef struct {
     expected_type type;
@@ -87,6 +87,15 @@ static int callback(void *data, int argc, char **argv, char **names) {
             } else goto multiple_columns;
             break;
 
+        case STR:
+            if(argc == 1){
+                if(!argv[0] || strcmp(argv[0], expect->value.s) != 0){
+                    printf("Error: expected from %s: \"%s\", got \"%s\"\n", names[0], expect->value.s, argv[0] ? argv[0] : "NULL");
+                    return SQLITE_ERROR;
+                }
+            } else goto multiple_columns;
+            break;
+
         default:
             printf("Error: unknown expect type\n");
             return SQLITE_ERROR;
@@ -136,6 +145,16 @@ int db_expect_gt0 (sqlite3 *db, const char *sql) {
     return rc;
 }
 
+int db_expect_str (sqlite3 *db, const char *sql, const char *expect) {
+    expected_t data;
+    data.type = STR;
+    data.value.s = expect;
+
+    int rc = sqlite3_exec(db, sql, callback, &data, NULL);
+    if (rc != SQLITE_OK) printf("Error while executing %s: %s\n", sql, sqlite3_errmsg(db));
+    return rc;
+}
+
 int open_load_ext(const char *db_path, sqlite3 **out_db) {
     sqlite3 *db = NULL;
     int rc = sqlite3_open(db_path, &db);
@@ -224,7 +243,7 @@ int test_init (const char *db_path, int init) {
     snprintf(sql, sizeof(sql), "INSERT INTO users (id, name) VALUES ('%s', '%s');", value, value);
     rc = db_exec(db, sql); RCHECK
     rc = db_expect_int(db, "SELECT COUNT(*) as count FROM users;", 1); RCHECK
-    rc = db_expect_gt0(db, "SELECT cloudsync_network_sync(250,10);"); RCHECK
+    rc = db_expect_gt0(db, "SELECT cloudsync_network_sync(250,10) ->> '$.receive.rows';"); RCHECK
     rc = db_expect_gt0(db, "SELECT COUNT(*) as count FROM users;"); RCHECK
     rc = db_expect_gt0(db, "SELECT COUNT(*) as count FROM activities;"); RCHECK
     rc = db_expect_int(db, "SELECT COUNT(*) as count FROM workouts;", 0); RCHECK
@@ -305,7 +324,7 @@ int test_enable_disable(const char *db_path) {
     // init network with connection string + apikey
     rc = db_exec(db2, network_init); RCHECK
 
-    rc = db_expect_gt0(db2, "SELECT cloudsync_network_sync(250,10);"); RCHECK
+    rc = db_expect_gt0(db2, "SELECT cloudsync_network_sync(250,10) ->> '$.receive.rows';"); RCHECK
 
     snprintf(sql, sizeof(sql), "SELECT COUNT(*) FROM users WHERE name='%s';", value);
     rc = db_expect_int(db2, sql, 0); RCHECK