docs: update API.md and README.md to match the current implementation

Author: andinux

API.md

@@ -24,11 +24,11 @@ This document provides a reference for the SQLite functions provided by the `sql
   - [`cloudsync_network_cleanup()`](#cloudsync_network_cleanup)
   - [`cloudsync_network_set_token()`](#cloudsync_network_set_tokentoken)
   - [`cloudsync_network_set_apikey()`](#cloudsync_network_set_apikeyapikey)
-  - [`cloudsync_network_has_unsent_changes()`](#cloudsync_network_has_unsent_changes)
   - [`cloudsync_network_send_changes()`](#cloudsync_network_send_changes)
   - [`cloudsync_network_check_changes()`](#cloudsync_network_check_changes)
   - [`cloudsync_network_sync()`](#cloudsync_network_syncwait_ms-max_retries)
   - [`cloudsync_network_reset_sync_version()`](#cloudsync_network_reset_sync_version)
+  - [`cloudsync_network_has_unsent_changes()`](#cloudsync_network_has_unsent_changes)
   - [`cloudsync_network_logout()`](#cloudsync_network_logout)
 
 ---
@@ -357,34 +357,27 @@ SELECT cloudsync_network_set_apikey('your_api_key');
 
 ---
 
-### `cloudsync_network_has_unsent_changes()`
+### `cloudsync_network_send_changes()`
 
-**Description:** Checks if there are any local changes that have not yet been sent to the remote server.
+**Description:** Sends all unsent local changes to the remote server.
 
 **Parameters:** None.
 
-**Returns:** 1 if there are unsent changes, 0 otherwise.
-
-**Example:**
+**Returns:** A JSON string with the sync status:
 
-```sql
-SELECT cloudsync_network_has_unsent_changes();
+```json
+{"status":"synced|syncing|out-of-sync|error", "localVersion": N, "serverVersion": N}
 ```
 
----
-
-### `cloudsync_network_send_changes()`
-
-**Description:** Sends all unsent local changes to the remote server.
-
-**Parameters:** None.
-
-**Returns:** None.
+- `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.
 
 **Example:**
 
 ```sql
 SELECT cloudsync_network_send_changes();
+-- '{"status":"synced","localVersion":5,"serverVersion":5}'
 ```
 
 ---
@@ -399,16 +392,22 @@ This function is designed to be called periodically to keep the local database i
 To force an update and wait for changes (with a timeout), use [`cloudsync_network_sync(wait_ms, max_retries)`].
 
 If the network is misconfigured or the remote server is unreachable, the function returns an error.
-On success, it returns `SQLITE_OK`, and the return value indicates how many changes were downloaded and applied.
 
 **Parameters:** None.
 
-**Returns:** The number of changes downloaded. Errors are reported via the SQLite return code.
+**Returns:** A JSON string with the number of changes applied:
+
+```json
+{"rowsReceived": N}
+```
+
+- `rowsReceived`: The number of rows downloaded and applied to the local database.
 
 **Example:**
 
 ```sql
 SELECT cloudsync_network_check_changes();
+-- '{"rowsReceived":3}'
 ```
 
 ---
@@ -425,13 +424,23 @@ 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:** The number of changes downloaded. Errors are reported via the SQLite return code.
+**Returns:** A JSON string with the full sync result:
+
+```json
+{"status":"synced|syncing|out-of-sync|error", "localVersion": N, "serverVersion": N, "rowsReceived": N}
+```
+
+- `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.
 
 **Example:**
 
 ```sql
 -- Perform a single synchronization cycle
 SELECT cloudsync_network_sync();
+-- '{"status":"synced","localVersion":5,"serverVersion":5,"rowsReceived":3}'
 
 -- Perform a synchronization cycle with custom retry settings
 SELECT cloudsync_network_sync(500, 3);
@@ -455,9 +464,25 @@ SELECT cloudsync_network_reset_sync_version();
 
 ---
 
+### `cloudsync_network_has_unsent_changes()`
+
+**Description:** Checks if there are any local changes that have not yet been sent to the remote server.
+
+**Parameters:** None.
+
+**Returns:** 1 if there are unsent changes, 0 otherwise.
+
+**Example:**
+
+```sql
+SELECT cloudsync_network_has_unsent_changes();
+```
+
+---
+
 ### `cloudsync_network_logout()`
 
-**Description:** Logs out the current user and cleans up all local data from synchronized tables. This function deletes and then re-initializes synchronized tables, useful for switching users or resetting the local database. **Warning:** This function deletes all data from synchronized tables. Use with caution.
+**Description:** Logs out the current user and cleans up all local data from synchronized tables. This function deletes and then re-initializes synchronized tables, useful for switching users or resetting the local database. **Warning:** This function deletes all data from synchronized tables. Use with caution. Consider calling [`cloudsync_network_has_unsent_changes()`](#cloudsync_network_has_unsent_changes) before logout to check for unsent local changes and warn the user before data that has not been fully synchronized to the remote server is deleted.
 
 **Parameters:** None.
 

README.md

@@ -50,21 +50,24 @@ The sync layer is tightly integrated with [**SQLite Cloud**](https://sqlitecloud
 
 ## Row-Level Security
 
-Thanks to the underlying SQLite Cloud infrastructure, **SQLite Sync supports Row-Level Security (RLS)**—allowing you to define **precise access control at the row level**:
+Thanks to the underlying SQLite Cloud infrastructure, **SQLite Sync supports Row-Level Security (RLS)**—allowing you to use a **single shared cloud database** while each client only sees and modifies its own data. RLS policies are enforced on the server, so the security boundary is at the database level, not in application code.
 
 - Control not just who can read or write a table, but **which specific rows** they can access.
-- Enforce security policies on the server—no need for client-side filtering.
+- Each device syncs only the rows it is authorized to see—no full dataset download, no client-side filtering.
 
 For example:
 
 - User A can only see and edit their own data.
 - User B can access a different set of rows—even within the same shared table.
 
-**Benefits of RLS**:
+**Benefits**:
 
-- **Data isolation**: Ensure users only access what they’re authorized to see.
-- **Built-in privacy**: Security policies are enforced at the database level.
-- **Simplified development**: Reduce or eliminate complex permission logic in your application code.
+- **Single database, multiple tenants**: One cloud database serves all users. RLS policies partition data per user or role, eliminating the need to provision separate databases.
+- **Efficient sync**: Each client downloads only its authorized rows, reducing bandwidth and local storage.
+- **Server-enforced security**: Policies are evaluated on the server during sync. A compromised or modified client cannot bypass access controls.
+- **Simplified development**: No need to implement permission logic in your application—define policies once in the database and they apply everywhere.
+
+For more information, see the [SQLite Cloud RLS documentation](https://docs.sqlitecloud.io/docs/rls).
 
 ### What Can You Build with SQLite Sync?
 
@@ -102,7 +105,12 @@ SQLite Sync is ideal for building collaborative and distributed apps across web,
 
 ## Documentation
 
-For detailed information on all available functions, their parameters, and examples, refer to the [comprehensive API Reference](./API.md).
+For detailed information on all available functions, their parameters, and examples, refer to the [comprehensive API Reference](./API.md). The API includes:
+
+- **Configuration Functions** — initialize, enable, and disable sync on tables
+- **Helper Functions** — version info, site IDs, UUID generation
+- **Schema Alteration Functions** — safely alter synced tables
+- **Network Functions** — connect, authenticate, send/receive changes, and monitor sync status
 
 ## Installation
 
@@ -284,12 +292,13 @@ SELECT cloudsync_network_set_apikey('your-api-key-here');
 -- Or use token authentication (required for Row-Level Security)
 -- SELECT cloudsync_network_set_token('your_auth_token');
 
--- Sync with cloud: send local changes, then check the remote server for new changes 
+-- Sync with cloud: send local changes, then check the remote server for new changes
 -- and, if a package with changes is ready to be downloaded, applies them to the local database
 SELECT cloudsync_network_sync();
--- Keep calling periodically. The function returns > 0 if data was received
--- In production applications, you would typically call this periodically
--- rather than manually (e.g., every few seconds)
+-- Returns a JSON string with sync status, e.g.:
+-- '{"status":"synced","localVersion":5,"serverVersion":5,"rowsReceived":3}'
+-- Keep calling periodically. In production applications, you would typically
+-- call this periodically rather than manually (e.g., every few seconds)
 SELECT cloudsync_network_sync();
 
 -- Before closing the database connection
@@ -314,9 +323,9 @@ SELECT cloudsync_init('my_data');
 SELECT cloudsync_network_init('sqlitecloud://your-project-id.sqlite.cloud/database.sqlite');
 SELECT cloudsync_network_set_apikey('your-api-key-here');
 
--- Sync to get data from the first device 
+-- Sync to get data from the first device
 SELECT cloudsync_network_sync();
--- repeat until data is received (returns > 0)
+-- Repeat — check rowsReceived in the JSON result to see if data was received
 SELECT cloudsync_network_sync();
 
 -- View synchronized data
@@ -454,12 +463,6 @@ Be aware that certain types of triggers can cause errors during synchronization
 - If a trigger modifies a table that is also synchronized with SQLite Sync, changes performed by the trigger may be applied twice during the merge operation
 - This can lead to constraint violations or unexpected data states depending on the table's constraints
 
-**Column-by-Column Processing**
-- SQLite Sync applies changes column-by-column during synchronization
-- UPDATE triggers may be called multiple times for a single row as each column is processed
-- This can result in unexpected trigger behavior
-
-
 
 ## License