fix(sync): implement WiFi request handling for various sync operations and...

    UIManager:show(widget)

end

---Settings:configureSyncDelayAfterConnect.

function Settings:configureSyncDelayAfterConnect(parent)

    local SpinWidget = require("ui/widget/spinwidget")

    local widget = SpinWidget:new{

        text = _("Wait this many seconds after WiFi is connected before running sync."),

        value = parent.sync_delay_after_connect_seconds or 0,

        value_min = 0,

        value_max = 300,

        value_step = 1,

        value_hold_step = 5,

        ok_text = _("Set"),

        title_text = _("Sync delay after connect (seconds)"),

        default_value = 0,

        callback = function(spin)

            local n = math.floor(tonumber(spin.value) or 0)

            if n < 0 then n = 0 end

            local success = parent.settings:saveSetting("sync_delay_after_connect_seconds", n)

            if success ~= false then

                parent.sync_delay_after_connect_seconds = n

                parent.settings:flush()

                UIManager:show(InfoMessage:new{

                    text = T(_("Sync delay after connect set to %1s"), tostring(n)),

                    timeout = 2,

                })

            else

                UIManager:show(InfoMessage:new{

                    text = _("Failed to save setting. Check logs for details."),

                    timeout = 3,

                })

            end

        end,

    }

    UIManager:show(widget)

end

---Settings:showVersion.

function Settings:showVersion(parent)

    local version_info = require("plugin_version")

        progress_decimal_places       = parent.progress_decimal_places,

        network_connect_timeout_seconds = parent.network_connect_timeout_seconds,

        network_connect_run_until_connect = parent.network_connect_run_until_connect,

        sync_delay_after_connect_seconds = parent.sync_delay_after_connect_seconds,

        force_push_session_on_suspend = parent.force_push_session_on_suspend,

        connect_network_on_suspend    = parent.connect_network_on_suspend,

        sync_mode                     = parent.sync_mode,

Requires BookLore credentials and server URL to be configured. See [Connection Setup](@/configuration/authentication.md).

If WiFi is currently disconnected, the action attempts to enable/connect WiFi automatically before matching starts.

---

## View Match Statistics

Requires BookLore credentials and server URL to be configured.

If WiFi is disconnected, the plugin attempts to enable/connect WiFi first. After upload completes, KOReader's native **Action when done with Wi-Fi** policy is applied.

---

## Sync Re-matched Sessions

Requires BookLore credentials and server URL to be configured.

If WiFi is disconnected, the plugin attempts to enable/connect WiFi first. After upload completes, KOReader's native **Action when done with Wi-Fi** policy is applied.

---

## Manual Matching

After a match is confirmed the book's `book_id` is written to the local cache and any pending sessions for that book are synced automatically.

Requires BookLore credentials and server URL to be configured. See [Connection Setup](@/configuration/authentication.md).

If WiFi is disconnected, the action attempts to enable/connect WiFi automatically before the matching flow opens.

![Sync menu with pending entries](../sync_menu.png)

Immediately uploads all pending sessions, ratings, annotations, bookmarks, and progress updates to the server.

If WiFi is not already connected, this action can enable/connect WiFi first, run sync, then hand control back to KOReader's native post-WiFi action flow.

The label shows the current queue sizes when items are waiting - for example **Sync Pending Now (3S, 1A, 2R, 1B, 4P)** means 3 sessions, 1 annotation, 2 ratings, 1 bookmark, and 4 progress updates are queued. Only non-zero counts are shown. The entry is greyed out when all queues are empty.

Uploads proceed in order: book IDs are resolved first, then ratings, then annotations, then bookmarks, then progress updates, then sessions. Sessions are sent in a batch of up to 100 at a time. Any session whose BookLore book ID is not yet known is resolved against the server first; if resolution fails, that session is skipped and retried next time.

Attempts to resolve books in the local cache that do not yet have a BookLore ID. The label shows the unmatched count when it is greater than zero - for example **Match Unmatched Books (4)**. The entry is greyed out when all books are already matched or the cache is empty.

A network connection is required. If the device is offline, a brief error toast is shown and nothing further happens.

A network connection is required. If the device is offline, the plugin first attempts to enable/connect WiFi automatically, then proceeds.

If WiFi cannot be enabled (or AirPlane Mode is active), matching is skipped and a brief toast is shown.

**Automatic resolution**

**Tools → BookLore Sync → Sync & Cache → Advanced**

- **Re-match All Books in Cache** resets all stored book IDs and re-resolves them from the server. Use this when the server library was rebuilt and IDs changed.

- **Re-sync Stored Metadata** re-fetches server metadata for matched cached books (for example server pagecount) without resetting matches.

- **Clear...** opens a selective clear dialog for synced-history tables:

  - Historical sessions

  - Synced annotations

| Trigger | Behaviour |

|---------|-----------|

| **Device suspend** | In **Automatic** sync mode, session + current progress are queued and upload is attempted immediately |

| **Device suspend** | In **Automatic** sync mode, session + current progress are queued and uploaded immediately **only if network is already connected** |

| **Session end** | In **Automatic** sync mode, sync is attempted after every valid session |

| **Device resume** | In **Automatic** sync mode, deferred background sync runs 15 seconds after wake |

| **Device resume** | In **Automatic** sync mode, deferred background sync runs after wake **only when network is already connected** |

| **Network connected** | Immediate sync when network becomes available (if a wake sync was pending) |

| **Manual Sync Now** | Triggered by **Tools → BookLore Sync → Sync & Cache → Sync Pending Now** |

| **Dispatcher action** | `SyncBooklorePending` can be assigned to a button or gesture |

BookLore Sync no longer uses a WiFi confirmation prompt setting.

- In **Automatic** sync mode, sync actions may enable/connect WiFi automatically when needed.

- In **Automatic** sync mode, manual actions may enable/connect WiFi when needed (for example **Sync Pending Now**).

- Suspend/resume automatic background sync does **not** try to connect WiFi. It runs only when a network connection is already active.

- In **Manual only (cache everything)** mode, automatic network sync is disabled and data remains queued until you run a manual sync action.

You can tune startup timing for flaky networks in:

**Tools → BookLore Sync → Sync Behavior → Sync delay after connect**

This adds a configurable wait (seconds) after WiFi connect succeeds and before sync requests are sent.

---

## Post-sync WiFi handling

- **Turn off**

- **Prompt**

This behavior is applied for manual actions that can enable WiFi:

For one-shot upload/download actions, this behavior is applied when the action had to enable WiFi:

- **Sync Pending Now**

- **Pull current book progress**

- **Push current book progress**

- **Sync from Booklore Shelf**

- **Re-sync All Historical**

- **Sync Re-matched Sessions**

- **Re-sync Stored Metadata**

For interactive matching workflows, WiFi is enabled/connect-on-demand but intentionally left up for the flow:

- **Match Unmatched Books**

- **Re-match All Books in Cache**

- **Match Historical Sessions**

- **Manual Matching**

The post-sync action only runs when WiFi was initially off. If WiFi was already connected before the action, the plugin does not change WiFi state.

If the community **AirPlane Mode** plugin is active (`airplanemode = true` in KOReader settings), BookLore Sync does not attempt to enable WiFi.

If you enable **Integrations → Airplanemode plugin → Switch sync mode based on airplane status**, the plugin also overrides **Sync Mode** automatically:

- AirPlane Mode ON → Sync Mode set to **Manual**

- AirPlane Mode OFF → Sync Mode set to **Automatic**

When enabled, the plugin shows:

> **Airplanemode integration enabled. This overrides Sync Mode based on airplane status.**

In that state, network actions are skipped and queued items remain pending until AirPlane Mode is disabled.

When you manually run **Sync Pending Now** while AirPlane Mode is active, the plugin shows:

When a network action is started while AirPlane Mode is active, the plugin shows:

> **AirPlane Mode is enabled - pending items remain queued**

> **AirPlane Mode is enabled - network sync skipped**

---