# Sync Flow: Transient

## Overview

The plugin uses a "save locally, retry remotely later" pattern. Local settings are never lost, and the plugin silently retries the API push each time an admin opens the settings page, for up to a day.

Syncing **only** happens when an admin visits `Settings > Inline Feedback` in wp-admin. The frontend widget makes zero API calls and triggers no sync.

## Flow Diagram

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                          ADMIN SAVES SETTINGS                                   │
│                        handle_save_settings()                                   │
└──────────────────────────────┬──────────────────────────────────────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │ Save options locally │
                    │  (always succeeds)  │
                    └──────────┬──────────┘
                               │
                        ┌──────┴──────┐
                        │ Connected?  │
                        └──────┬──────┘
                               │
                  ┌────────────┴────────────┐
                  ▼                         ▼
            ┌──────────┐            ┌──────────────┐
            │    No    │            │ PUT to API   │
            └────┬─────┘            └──────┬───────┘
                 │                         │
                 │                ┌────────┬┴────────┐
                 │                ▼        ▼         ▼
                 │          ┌────────┐ ┌───────┐ ┌──────────┐
                 │          │Success │ │ 401   │ │ Other    │
                 │          └───┬────┘ │ Auth  │ │ Error    │
                 │              │      │ Error │ └────┬─────┘
                 │              │      └───┬───┘      │
                 │              │          │          │
                 │              ▼          ▼          ▼
                 │       ┌──────────┐ ┌────────┐ ┌───────────────────────┐
                 │       │ delete   │ │ Wipe   │ │ set_transient         │
                 │       │transient │ │connect │ │ inlf_sync_pending     │
                 │       └────┬─────┘ │& redir │ │ (24 hr TTL)          │
                 │            │       └────────┘ └───────────┬───────────┘
                 │            │                              │
                 ▼            ▼                              ▼
          ┌────────────────────────┐              ┌───────────────────────┐
          │ Redirect: settings-saved│             │ Redirect: settings-   │
          └────────────────────────┘              │ saved + sync-error    │
                                                  └───────────────────────┘


┌─────────────────────────────────────────────────────────────────────────────────┐
│                   ADMIN VISITS SETTINGS PAGE (GET)                               │
│                       sync_config_from_api()                                    │
└──────────────────────────────┬──────────────────────────────────────────────────┘
                               │
                        ┌──────┴──────────────┐
                        │ inlf_sync_pending   │
                        │ transient set?      │
                        └──────┬──────────────┘
                               │
                  ┌────────────┴────────────┐
                  ▼                         ▼
          ┌──────────────┐         ┌────────────────┐
          │     YES      │         │      NO        │
          │ retry_pending│         │ Pull remote    │
          │ _sync()      │         │ config (GET)   │
          └──────┬───────┘         └───────┬────────┘
                 │                         │
                 ▼                         ▼
          ┌──────────────┐         ┌────────────────┐
          │ PUT local    │         │ Overwrite local │
          │ settings     │         │ with remote     │
          │ to API       │         │ settings        │
          └──────┬───────┘         └────────────────┘
                 │
        ┌────────┼────────┐
        ▼        ▼        ▼
  ┌────────┐ ┌───────┐ ┌──────────┐
  │Success │ │ 401   │ │ Still    │
  │        │ │ Auth  │ │ failing  │
  └───┬────┘ └───┬───┘ └────┬─────┘
      │          │           │
      ▼          ▼           ▼
  ┌────────┐ ┌────────┐ ┌───────────────────┐
  │ delete │ │ delete │ │ Transient stays   │
  │transient│ │transient│ │ Retries on next  │
  │ Done   │ │+ wipe  │ │ page visit until  │
  └────────┘ │connect │ │ 24hr TTL expires  │
             └────────┘ └─────────┬─────────┘
                                  │
                                  ▼
                        ┌───────────────────┐
                        │ After 24hr expiry │
                        │ next visit does   │
                        │ normal GET pull   │
                        │ → remote wins     │
                        │ → local changes   │
                        │   silently lost   │
                        └───────────────────┘


┌─────────────────────────────────────────────────────────────────────────────────┐
│                       FRONTEND PAGE LOAD                                        │
│                     Inlf_Widget_Injector                                        │
└──────────────────────────────┬──────────────────────────────────────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │ Read local options  │
                    │ Output <script> tag │
                    │                     │
                    │ No API calls        │
                    │ No sync trigger     │
                    └─────────────────────┘
```

## Key Files

- `admin/class-admin-settings.php` — `handle_save_settings()`, `sync_config_from_api()`, `retry_pending_sync()`
- `includes/class-inline-feedback.php` — `clear_connection_options()` (cleanup on disconnect)
- `includes/class-widget-injector.php` — Frontend widget (read-only, no sync)

## Edge Case: 24-Hour Expiry

If the transient expires without a successful retry:
1. Local changes that failed to sync are silently lost
2. Next settings page visit pulls remote config and overwrites local
3. No admin notice or conflict detection exists for this scenario