ccn/Services/Website/Sources/Library/Internal/Extensions/String+Routes.swift

import Foundation

extension String {
    /// A namespace for the paths of the site's screens.
    ///
    /// Screens not built yet are listed too, and answer with the not-found page until they are.
    enum Route {
        /// The account screen.
        static let account = "/account"
        /// The collection tracker.
        static let collection = "/collection"
        /// The events screen.
        static let events = "/events"
        /// The public grading guide.
        static let gradingGuide = "/grading-guide"
        /// The browse / home screen.
        static let home = "/"
        /// The message threads.
        static let messages = "/messages"
        /// The open-a-shop onboarding.
        static let openShop = "/sell/open-a-shop"
        /// The privacy statement.
        static let privacy = "/privacy"
        /// The passkey recovery screen.
        static let recover = "/recover"
        /// The search results screen.
        static let search = "/search"
        /// The seller dashboard.
        static let sellerDashboard = "/sell"
        /// The rules sellers agree to.
        static let sellerRules = "/seller-rules"
        /// The series index.
        static let series = "/series"
        /// The passkey sign-in screen.
        static let signIn = "/sign-in"
        /// The path a sign-out is posted to.
        static let signOut = "/sign-out"
        /// The terms of service.
        static let terms = "/terms"
        /// The want list.
        static let wants = "/wants"

        /// The path an offer is answered at.
        /// - Parameter id: the offer's identifier.
        static func answer(
            offer id: UUID
        ) -> String {
            "\(sellerDashboard)/offers/\(id.uuidString.lowercased())"
        }

        /// The path buying a listing outright starts at.
        /// - Parameter slug: the listing's URL slug.
        static func buy(
            _ slug: String
        ) -> String {
            "\(listing(slug))/buy"
        }

        /// The path of a conversation.
        /// - Parameter id: the conversation's identifier.
        static func conversation(
            _ id: UUID
        ) -> String {
            "\(messages)/\(id.uuidString.lowercased())"
        }

        /// The path a gated action leads to: the action itself when signed in, else the sign-in screen, returning to where the action was taken.
        /// - Parameters:
        ///   - path: the action's own path.
        ///   - origin: the path of the screen the action is taken on.
        ///   - viewer: the signed-in viewer, or `nil` when signed out.
        static func gated(
            _ path: String,
            from origin: String,
            viewer: Viewer?
        ) -> String {
            viewer == nil ? signIn(returningTo: origin) : path
        }

        /// The path of a listing's detail screen.
        /// - Parameter slug: the listing's URL slug.
        static func listing(
            _ slug: String
        ) -> String {
            "/listing/\(slug)"
        }

        /// The path of a new message thread about a listing.
        /// - Parameter slug: the listing's URL slug.
        static func message(
            listing slug: String
        ) -> String {
            "\(messages)/new?listing=\(slug)"
        }

        /// The path of a new message thread with a shop.
        /// - Parameter slug: the shop's URL slug.
        static func message(
            shop slug: String
        ) -> String {
            "\(messages)/new?shop=\(slug)"
        }

        /// The path of the offer sheet for a listing.
        /// - Parameter slug: the listing's URL slug.
        static func offer(
            _ slug: String
        ) -> String {
            "\(listing(slug))/offer"
        }

        /// The path of a sale record.
        /// - Parameter number: the record's number.
        static func sale(
            _ number: Int
        ) -> String {
            "/sales/\(number)"
        }

        /// The path of a shop's public screen.
        /// - Parameter slug: the shop's URL slug.
        static func shop(
            _ slug: String
        ) -> String {
            "/shop/\(slug)"
        }

        /// The path to return to after signing in: the one asked for when it stays on this site, else the home screen.
        ///
        /// Only a rooted path is followed. Anything else — another origin, a scheme-relative `//host`, a backslash a browser reads as a slash —
        /// would turn the sign-in into an open redirect.
        /// - Parameter path: the path asked for, as the `return` parameter carried it.
        static func safeReturn(
            _ path: String?
        ) -> String {
            guard
                let path,
                path.hasPrefix("/"),
                !path.hasPrefix("//"),
                !path.contains("\\"),
                !path.unicodeScalars.contains(where: { $0.properties.generalCategory == .control })
            else {
                return home
            }

            return path
        }

        /// The path of the sign-in screen, returning to the given path afterwards.
        /// - Parameter path: the path the visitor's gated action started from.
        static func signIn(
            returningTo path: String
        ) -> String {
            "\(signIn)?return=\(path.addingPercentEncoding(withAllowedCharacters: .urlQueryValueAllowed) ?? "")"
        }
    }
}

// MARK: - Constants

private extension CharacterSet {
    /// The characters a query value carries unescaped.
    static let urlQueryValueAllowed = CharacterSet.urlQueryAllowed.subtracting(.init(charactersIn: "&=+?#"))
}