Improve robustness of the URL handler

This commit improves reliability on the handling of
external URLs.

This was achieved through the following improvements:
1. The URL handler interface is now well-defined, with more clear inputs
   and outputs, to avoid silent failures and error paths that are hard to see
   within convoluted logic paths
2. Side effects during URL parsing were almost completely removed for
   more predictable behavior
3. Error handling logic was added to present errors to the user in a user-friendly manner,
   instead of silently failing
4. Event loading logic was moved into a special new thread view, which
   makes its own internal state evident to the user (i.e. whether
   the note is loading, loaded, or if the note could not be found)

These changes make the URL opening logic more predictable, easy to
refactor, and helps ensure the user always gets some outcome from
opening a URL, even if it means showing a "not found" or "error" screen,
to eliminate cases where nothing seems to happen.

Closes: https://github.com/damus-io/damus/issues/2429
Changelog-Fixed: Improved robustness of the URL handler
Changelog-Added: Added user-friendly error view for errors around the app that would not fit in other places
Signed-off-by: Daniel D’Aquino <daniel@daquino.me>

damus/Models/Purple/DamusPurple.swift

@@ -363,6 +363,42 @@ class DamusPurple: StoreObserverDelegate {
         return freshly_completed_checkouts
     }
     
+    /// Handles a Purple URL
+    /// - Parameter purple_url: The Purple URL being opened
+    /// - Returns: A view to be shown in the UI
+    @MainActor
+    func handle(purple_url: DamusPurpleURL) async -> ContentView.ViewOpenAction {
+        if case let .welcome(checkout_id) = purple_url.variant {
+            // If this is a welcome link, do the following before showing the onboarding screen:
+            // 1. Check if this is legitimate and good to go.
+            // 2. Mark as complete if this is good to go.
+            let is_good_to_go = try? await check_and_mark_ln_checkout_is_good_to_go(checkout_id: checkout_id)
+            switch is_good_to_go {
+            case .some(let is_good_to_go):
+                if is_good_to_go {
+                    return .sheet(.purple(purple_url))  // ALL GOOD, SHOW WELCOME SHEET
+                }
+                else {
+                    return .sheet(.error(.init(
+                        user_visible_description: NSLocalizedString("You clicked on a Purple welcome link, but it does not look like the checkout is completed yet. This is likely a bug.", comment: "Error label upon continuing in the app from a Damus Purple purchase"),
+                        tip: NSLocalizedString("Please double-check the checkout web page, or go to the Side Menu → \"Purple\" to check your account status. If you have already paid, but still don't see your account active, please save the URL of the checkout page where you came from, contact our support, and give us the URL to help you with this issue.", comment: "User-facing tips on what to do if a Purple welcome link doesn't work"),
+                        technical_info: "Handling Purple URL \"\(purple_url)\" failed, the `is_good_to_go` result was `\(is_good_to_go)`"
+                    )))
+                }
+            case .none:
+                return .sheet(.error(.init(
+                    user_visible_description: NSLocalizedString("You clicked on a Purple welcome link, but we could not find your checkout. This is likely a bug.", comment: "Error label upon continuing in the app from a Damus Purple purchase"),
+                    tip: NSLocalizedString("Please double-check the checkout web page, or go to the Side Menu → \"Purple\" to check your account status. If you have already paid, but still don't see your account active, please save the URL of the checkout page where you came from, contact our support, and give us the URL to help you with this issue", comment: "User-facing tips on what to do if a Purple welcome link doesn't work"),
+                    technical_info: "Handling Purple URL \"\(purple_url)\" failed, the `is_good_to_go` result was `\(String(describing: is_good_to_go))`"
+                )))
+            }
+        }
+        else {
+            // Show the purple url contents
+            return .sheet(.purple(purple_url))
+        }
+    }
+    
     @MainActor
     /// This function checks the status of a specific checkout id with the server
     /// You should use this result immediately, since it will internally be marked as handled

damus/Models/Purple/DamusPurpleURL.swift

@@ -2,7 +2,7 @@
 //  DamusPurpleURL.swift
 //  damus
 //
-//  Created by Daniel Nogueira on 2024-01-13.
+//  Created by Daniel D'Aquino on 2024-01-13.
 //
 
 import Foundation