@moifort/stack 0.0.0-stage → 0.1.0

package/templates/ios/ios/{{APP_NAME}}/Shared/CursorPage.swift

@@ -0,0 +1,26 @@
+import Foundation
+
+/// One page of a list the server cuts by cursor: its rows, whether more
+/// follow, and the cursor to ask the next page after. The cursor is the
+/// server's to make; the app only hands it back.
+struct CursorPage<Item: Sendable>: Sendable {
+    let items: [Item]
+    let hasMore: Bool
+    /// Nil on an empty page.
+    let endCursor: String?
+}
+
+extension CursorPage {
+    /// A page cut from rows already in memory, as the server cuts its own:
+    /// after the row the cursor names, from the top when it names none. For
+    /// the showcase, the previews and the tests.
+    init(_ rows: [Item], limit: Int, after: String?, cursor: (Item) -> String) {
+        let start = after.flatMap { after in rows.firstIndex { cursor($0) == after }.map { $0 + 1 } } ?? 0
+        let page = Array(rows.dropFirst(start).prefix(limit))
+        self.init(
+            items: page,
+            hasMore: start + page.count < rows.count,
+            endCursor: page.last.map(cursor)
+        )
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/DataChanges.swift

@@ -0,0 +1,19 @@
+import Foundation
+
+extension Notification.Name {
+    /// Something changed on the server. Posted by `GraphQLHelpers.perform` after
+    /// every mutation that came back, so a list left open on another tab redraws
+    /// itself before the user gets back to it.
+    ///
+    /// One name for everything on purpose: lists are cheap to refetch, and naming
+    /// what changed for each screen to decide whether it cares is where stale rows
+    /// come from. Only screens listen; a page never subscribes.
+    static let dataDidChange = Notification.Name("DataDidChange")
+}
+
+/// What a single write changed, when it changed one thing: a list that has that
+/// row open patches it instead of reloading. A notice with no object may have
+/// changed anything. Add a case per kind of object the app edits one at a time.
+enum DataChange: Hashable, Sendable {
+    case item(id: String)
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/ErrorPresenter.swift

@@ -0,0 +1,62 @@
+import SwiftUI
+
+/// Captures errors from async API mutations so they can be surfaced in an alert
+/// instead of being silently discarded with `try?`.
+///
+/// Usage:
+/// ```swift
+/// @State private var errorPresenter = ErrorPresenter()
+///
+/// // In an action closure:
+/// await errorPresenter.run {
+///     try await BookAPI.rate(...)
+/// } onSuccess: {
+///     showFavorite = false
+/// }
+///
+/// // On the view (inside the sheet content if the action runs in a sheet,
+/// // so the sheet stays open on failure):
+/// .errorAlert(errorPresenter)
+/// ```
+@MainActor
+@Observable
+final class ErrorPresenter {
+    var message: String?
+    /// True while `run` is awaiting the network call — bind a button's spinner /
+    /// disabled state to this so every mutation shows a loader.
+    private(set) var isRunning = false
+
+    /// Runs `operation`. On success, calls `onSuccess` (dismiss the sheet, refresh, ...).
+    /// On failure, reports the error and stores its message so `.errorAlert` presents it;
+    /// `onSuccess` is NOT called, so the sheet stays open and the user can retry or cancel.
+    func run(
+        _ operation: @MainActor () async throws -> Void,
+        onSuccess: @MainActor () -> Void = {}
+    ) async {
+        isRunning = true
+        defer { isRunning = false }
+        do {
+            try await operation()
+            onSuccess()
+        } catch {
+            message = reportError(error)
+        }
+    }
+}
+
+extension View {
+    /// Presents an alert whenever the given presenter holds an error message.
+    func errorAlert(_ presenter: ErrorPresenter) -> some View {
+        alert(
+            "Une erreur est survenue",
+            isPresented: Binding(
+                get: { presenter.message != nil },
+                set: { if !$0 { presenter.message = nil } }
+            )
+        ) {
+            Button("OK") { presenter.message = nil }
+        } message: {
+            Text(presenter.message ?? "")
+        }
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/ErrorReporting.swift

@@ -0,0 +1,35 @@
+import Foundation
+import Sentry
+
+/// Reports an error to Sentry, unless it is a cancellation or a lost network,
+/// and returns the sentence to show the user.
+func reportError(_ error: Error) -> String {
+    let nsError = error as NSError
+    if !isCancellation(error) && !isConnectivityLoss(nsError) {
+        SentrySDK.capture(error: error)
+    }
+    return error.localizedDescription
+}
+
+/// The request was called off rather than refused: its task was cancelled, the
+/// user left the screen that asked. Nothing failed.
+func isCancellation(_ error: Error) -> Bool {
+    let nsError = error as NSError
+    return error is CancellationError
+        || (nsError.domain == NSURLErrorDomain && nsError.code == NSURLErrorCancelled)
+}
+
+/// The device lost its network, not the app its way. The user is told; Sentry
+/// has nothing to fix. The URL error may come wrapped, as the Firebase token
+/// fetch wraps its own network failure.
+private func isConnectivityLoss(_ error: NSError) -> Bool {
+    if error.domain == NSURLErrorDomain && [
+        NSURLErrorTimedOut,
+        NSURLErrorNetworkConnectionLost,
+        NSURLErrorNotConnectedToInternet,
+    ].contains(error.code) {
+        return true
+    }
+    guard let underlying = error.userInfo[NSUnderlyingErrorKey] as? NSError else { return false }
+    return isConnectivityLoss(underlying)
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/FeedbackReporting.swift

@@ -0,0 +1,42 @@
+import Foundation
+import OSLog
+import Sentry
+
+/// What the message is about. Travels as a Sentry tag so the inbox can be
+/// filtered on it.
+enum FeedbackKind: String {
+    case bug
+    case idea
+}
+
+/// Sends a message written by the user to the Sentry feedback inbox.
+///
+/// Only the message travels: no name, no email. `AuthSession` reports the uid
+/// and nothing else, and that uid is already on the scope, which is enough to
+/// reach the account behind the message.
+func sendFeedback(kind: FeedbackKind, message: String) {
+    #if DEBUG
+    // Sentry never starts in a Debug build, so `capture` below would silently
+    // drop the message. Logging it keeps the screen testable on the simulator.
+    // `notice` rather than `debug`: debug entries are not kept in the log store,
+    // so they cannot be read back after the fact with `log show`.
+    log.notice("feedback (\(kind.rawValue, privacy: .public)): \(message, privacy: .public)")
+    #endif
+
+    // The feedback envelope carries no tags of its own; the hub captures it with
+    // the current scope, so the tag has to sit there for the length of the call.
+    SentrySDK.configureScope { $0.setTag(value: kind.rawValue, key: feedbackKindTag) }
+    SentrySDK.capture(feedback: SentryFeedback(
+        message: message,
+        name: nil,
+        email: nil,
+        source: .custom
+    ))
+    SentrySDK.configureScope { $0.removeTag(key: feedbackKindTag) }
+}
+
+private let feedbackKindTag = "feedback.kind"
+
+#if DEBUG
+private let log = Logger(subsystem: "{{BUNDLE_ID}}", category: "feedback")
+#endif

package/templates/ios/ios/{{APP_NAME}}/Shared/FirebaseTokenInterceptor.swift

@@ -0,0 +1,49 @@
+import Apollo
+import FirebaseAuth
+import Foundation
+
+/// Injects the current Firebase user's ID token into every GraphQL request as
+/// `Authorization: Bearer <token>`. Firebase Auth refreshes the token under the
+/// hood so this is always fresh. Runs at the HTTP layer (Apollo 2.x) where the
+/// request is a plain `URLRequest`.
+///
+/// A refused token is where a dead session shows: when the account behind it
+/// is gone, the user is signed out rather than left on screens that can no
+/// longer load.
+struct FirebaseTokenInterceptor: HTTPInterceptor {
+    func intercept(
+        request: URLRequest,
+        next: NextHTTPInterceptorFunction
+    ) async throws -> HTTPResponse {
+        var request = request
+        if let currentUser = Auth.auth().currentUser {
+            do {
+                let token = try await currentUser.idToken()
+                request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+            } catch {
+                await AuthSession.dropSessionIfAccountIsGone()
+                throw error
+            }
+        }
+        let response = try await next(request)
+        if response.response.statusCode == 401 {
+            await AuthSession.dropSessionIfAccountIsGone()
+        }
+        return response
+    }
+}
+
+private extension User {
+    /// Async wrapper around Firebase's callback-based ID token fetch.
+    func idToken() async throws -> String {
+        try await withCheckedThrowingContinuation { continuation in
+            getIDToken { token, error in
+                if let error {
+                    continuation.resume(throwing: error)
+                } else {
+                    continuation.resume(returning: token ?? "")
+                }
+            }
+        }
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/GraphQLClient.swift

@@ -0,0 +1,54 @@
+import Apollo
+import ApolloAPI
+import Foundation
+
+/// Singleton ApolloClient configured for the Firebase Functions /graphql endpoint.
+/// Each request goes through:
+///   1. GraphQL interceptors — Apollo defaults + GraphQLLoggingInterceptor (logs errors)
+///   2. HTTP interceptors — FirebaseTokenInterceptor (injects Authorization: Bearer <ID Token>)
+///      then Apollo's ResponseCodeInterceptor
+final class GraphQLClient: @unchecked Sendable {
+    static let shared = GraphQLClient()
+
+    // Built once: recreating the store/transport per request would discard
+    // connection reuse. The base URL is read at init — changing the server URL
+    // in the debug settings requires an app restart.
+    let apollo: ApolloClient
+
+    private init() {
+        let url = APIClient.shared.baseURL.appendingPathComponent("graphql")
+        let store = ApolloStore()
+        let transport = RequestChainNetworkTransport(
+            urlSession: URLSession(configuration: .default),
+            interceptorProvider: AuthenticatedInterceptorProvider(),
+            store: store,
+            endpointURL: url
+        )
+        apollo = ApolloClient(networkTransport: transport, store: store)
+    }
+}
+
+/// Adds our Firebase auth (HTTP) and error logging (GraphQL) interceptors on top
+/// of Apollo's default chain. Apollo 2.x makes `DefaultInterceptorProvider` final,
+/// so we conform to `InterceptorProvider` directly and re-list the defaults.
+struct AuthenticatedInterceptorProvider: InterceptorProvider {
+    func graphQLInterceptors<Operation: GraphQLOperation>(
+        for operation: Operation
+    ) -> [any GraphQLInterceptor] {
+        [
+            MaxRetryInterceptor(),
+            AutomaticPersistedQueryInterceptor(),
+            GraphQLLoggingInterceptor(),
+        ]
+    }
+
+    func httpInterceptors<Operation: GraphQLOperation>(
+        for operation: Operation
+    ) -> [any HTTPInterceptor] {
+        [
+            FirebaseTokenInterceptor(),
+            AcceptLanguageInterceptor(),
+            ResponseCodeInterceptor(),
+        ]
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/GraphQLHelpers.swift

@@ -0,0 +1,128 @@
+import Apollo
+import ApolloAPI
+import Foundation
+
+enum GraphQLHelpers {
+    /// Cache fully disabled: `.networkOnly` never reads the normalized store, and
+    /// nothing in the app watches or reads it, which avoids a class of stale and
+    /// normalization bugs. `requestTimeout` overrides the session's 60 s idle
+    /// limit for a query that may legitimately keep the server silent longer.
+    static func fetch<Q: GraphQLQuery>(
+        _ client: ApolloClient,
+        query: Q,
+        requestTimeout: TimeInterval? = nil
+    ) async throws -> Q.Data
+    where Q.ResponseFormat == SingleResponseFormat {
+        let response = try await calledOffWhenCancelled {
+            try await client.fetch(
+                query: query,
+                cachePolicy: .networkOnly,
+                requestConfiguration: requestTimeout.map { RequestConfiguration(requestTimeout: $0) }
+            )
+        }
+        return try unwrap(response)
+    }
+
+    /// Every mutation goes through here, and posts the one change notice once the
+    /// write landed, so no screen has to remember to.
+    ///
+    /// `changesData` is false for a mutation that changes nothing a list shows (a
+    /// sign-in, an account deletion): every open screen refetches on the notice,
+    /// so posting it for those costs requests for nothing. On by default: a new
+    /// mutation that forgets to say stays correct, just dearer.
+    ///
+    /// `concerning` names the one object a mutation changed, sent as the notice's
+    /// object: a list that knows what it has open can patch that row.
+    static func perform<M: GraphQLMutation>(
+        _ client: ApolloClient,
+        concerning change: DataChange? = nil,
+        mutation: M,
+        requestTimeout: TimeInterval? = nil,
+        changesData: Bool = true
+    ) async throws -> M.Data
+    where M.ResponseFormat == SingleResponseFormat {
+        let response = try await calledOffWhenCancelled {
+            try await client.perform(
+                mutation: mutation,
+                requestConfiguration: requestTimeout.map { RequestConfiguration(requestTimeout: $0) }
+            )
+        }
+        let data = try unwrap(response)
+        guard changesData else { return data }
+        await MainActor.run {
+            NotificationCenter.default.post(name: .dataDidChange, object: change)
+        }
+        return data
+    }
+
+    /// A request whose task was cancelled fails as a cancellation, whatever
+    /// Apollo made of it: Apollo 2.x may report `noResults` before the outer
+    /// stream closed on the cancellation.
+    private static func calledOffWhenCancelled<Response>(
+        _ request: () async throws -> Response
+    ) async throws -> Response {
+        do {
+            return try await request()
+        } catch ApolloClient.Error.noResults where Task.isCancelled {
+            throw CancellationError()
+        }
+    }
+
+    /// Turn a `GraphQLResponse` into its `Data`, surfacing GraphQL errors and
+    /// missing data as `APIError`.
+    private static func unwrap<O: GraphQLOperation>(_ response: GraphQLResponse<O>) throws -> O.Data {
+        if let errors = response.errors, !errors.isEmpty {
+            // The server names what went wrong in `extensions.code`: screens that
+            // react to a specific outcome match on it.
+            if let code = errors.compactMap({ $0.extensions?["code"] as? String }).first {
+                throw APIError.domain(code: code, messages: errors.compactMap(\.message))
+            }
+            throw APIError.graphQL(messages: errors.compactMap(\.message))
+        }
+        guard let data = response.data else { throw APIError.invalidResponse }
+        return data
+    }
+
+    /// Decode an ISO-8601 date string from a GraphQL DateTime scalar.
+    static func parseISO8601(_ string: String) -> Date? {
+        let withFraction = ISO8601DateFormatter()
+        withFraction.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        let withoutFraction = ISO8601DateFormatter()
+        withoutFraction.formatOptions = [.withInternetDateTime]
+        return withFraction.date(from: string) ?? withoutFraction.date(from: string)
+    }
+
+    /// An empty or blank optional string is absent (`.none`), never sent as `""`:
+    /// branded server fields refuse an empty value.
+    static func graphQLNullable(_ value: String?) -> GraphQLNullable<String> {
+        guard let value, !value.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        else { return .none }
+        return .some(value)
+    }
+
+    static func graphQLNullable<T>(_ value: T?) -> GraphQLNullable<T> {
+        value.map { .some($0) } ?? .none
+    }
+}
+
+enum APIError: LocalizedError {
+    case invalidResponse
+    case graphQL(messages: [String])
+    /// A refusal the server named, e.g. `NOT_FOUND`. Carries the code so a screen
+    /// can act on it rather than only show its message.
+    case domain(code: String, messages: [String])
+
+    var domainCode: String? {
+        if case .domain(let code, _) = self { return code }
+        return nil
+    }
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidResponse:
+            return String(localized: "Réponse invalide du serveur")
+        case .graphQL(let messages), .domain(_, let messages):
+            return messages.joined(separator: " · ")
+        }
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/GraphQLLoggingInterceptor.swift

@@ -0,0 +1,28 @@
+import Apollo
+import ApolloAPI
+import Foundation
+import OSLog
+
+private let log = Logger(subsystem: "{{BUNDLE_ID}}", category: "graphql")
+
+/// Logs any GraphQL errors returned for an operation. Post-flight work happens in
+/// the `.map` of the result stream (Apollo 2.x interceptor model).
+struct GraphQLLoggingInterceptor: GraphQLInterceptor {
+    func intercept<Request: GraphQLRequest>(
+        request: Request,
+        next: NextInterceptorFunction<Request>
+    ) async throws -> InterceptorResultStream<Request> {
+        await next(request).map { parsed in
+            if let errors = parsed.result.errors, !errors.isEmpty {
+                for error in errors {
+                    let code = (error.extensions?["code"] as? String) ?? "<no code>"
+                    let message = error.message ?? "<no message>"
+                    log.error(
+                        "\(Request.Operation.operationName, privacy: .public) [\(code, privacy: .public)] \(message, privacy: .public)"
+                    )
+                }
+            }
+            return parsed
+        }
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/LoadGate.swift

@@ -0,0 +1,30 @@
+/// One load of each kind at a time. A screen asks for the same section from
+/// several places — its appearance, a change notice, a sheet closing — and
+/// each used to start a request of its own, side by side with the one already
+/// on its way.
+///
+/// Asked while that kind is running, a load either rides on it (`again:
+/// false`: what is coming is what was wanted) or has it run once more when it
+/// ends (`again: true`: a write landed since it set out), however many times
+/// it was asked meanwhile.
+@MainActor
+final class LoadGate<Kind: Hashable> {
+    private var running: Set<Kind> = []
+    private var stale: Set<Kind> = []
+
+    /// A write landed since the load running for that kind set out: what it
+    /// brings back is already behind.
+    func isStale(_ kind: Kind) -> Bool { stale.contains(kind) }
+
+    func run(_ kind: Kind, again: Bool, _ load: () async -> Void) async {
+        guard running.insert(kind).inserted else {
+            if again { stale.insert(kind) }
+            return
+        }
+        defer { running.remove(kind) }
+        repeat {
+            stale.remove(kind)
+            await load()
+        } while stale.contains(kind) && !Task.isCancelled
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/Secrets.swift.example

@@ -0,0 +1,9 @@
+import Foundation
+
+/// Local-only secrets. Copy to Secrets.swift (gitignored) and fill in.
+/// Auth uses Firebase ID tokens; the legacy REST API token is only used by
+/// tooling/UITests.
+enum Secrets {
+    static let apiToken = ""  // legacy REST API token, leave empty if unused
+    static let sentryDsn = ""  // Sentry DSN for crash/error reporting, leave empty to disable
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/Services/AppSupportGate.swift

@@ -0,0 +1,50 @@
+import Foundation
+import Observation
+
+/// Blocks the app when the running build is older than the backend's minimum
+/// supported iOS build (`GET /app-config`, public). Checked at launch and on
+/// every return to the foreground, so a backend deploy that raises the floor
+/// also catches apps that were already open. Fails open: a network or decoding
+/// error never blocks the app.
+@MainActor
+@Observable
+final class AppSupportGate {
+    enum State: Equatable {
+        case supported
+        case updateRequired(appStoreURL: URL)
+    }
+
+    /// Defaults to `.supported` so launch never waits on the check; a blocked
+    /// build may flash the regular UI for one round-trip before the gate closes.
+    private(set) var state: State = .supported
+
+    private struct AppConfig: Decodable {
+        let minimumSupportedIOSBuild: Int
+        let appStoreUrl: URL
+    }
+
+    func check() async {
+        // A Debug build, from Xcode or scripts/install-device.sh, carries build 1:
+        // the first raised floor would lock the developer out of their own app.
+        #if DEBUG
+        return
+        #else
+        guard let build = Self.currentBuild else { return }
+        let url = APIClient.shared.baseURL.appendingPathComponent("app-config")
+        // Bypass URLCache: a stale floor would defeat the foreground re-check.
+        let request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData)
+        guard let (data, _) = try? await URLSession.shared.data(for: request),
+              let config = try? JSONDecoder().decode(AppConfig.self, from: data)
+        else { return }
+        state = build < config.minimumSupportedIOSBuild
+            ? .updateRequired(appStoreURL: config.appStoreUrl)
+            : .supported
+        #endif
+    }
+
+    /// `CFBundleVersion` is `git rev-list --count HEAD` at release time, so a
+    /// plain integer comparison is enough — no marketing-version parsing.
+    private static var currentBuild: Int? {
+        (Bundle.main.infoDictionary?["CFBundleVersion"] as? String).flatMap(Int.init)
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/Shell/StartupLoadingView.swift

@@ -0,0 +1,23 @@
+import SwiftUI
+
+/// The launch wait, centred in all available space. Every other wait (a screen
+/// loading, a list refreshing, a button working) takes the system `ProgressView`
+/// where it happens, never this.
+struct StartupLoadingView: View {
+    var label: LocalizedStringKey = "Chargement…"
+
+    var body: some View {
+        VStack(spacing: 16) {
+            ProgressView()
+                .controlSize(.large)
+            Text(label)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+}
+
+#Preview {
+    StartupLoadingView()
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/Shell/UpdateRequiredView.swift

@@ -0,0 +1,24 @@
+import SwiftUI
+
+/// Blocking screen shown when the running build is below the backend's minimum
+/// supported build. No dismissal: the only way forward is the App Store update.
+struct UpdateRequiredView: View {
+    let appStoreURL: URL
+
+    var body: some View {
+        ContentUnavailableView {
+            Label("Mise à jour requise", systemImage: "arrow.down.app")
+        } description: {
+            Text("Cette version de {{APP_NAME}} n'est plus compatible avec le serveur. La dernière version est disponible sur l'App Store.")
+        } actions: {
+            Link("Mettre à jour", destination: appStoreURL)
+                .font(.headline)
+                .buttonStyle(.borderedProminent)
+                .controlSize(.large)
+        }
+    }
+}
+
+#Preview {
+    UpdateRequiredView(appStoreURL: URL(string: "https://apps.apple.com/app/id6789688303")!)
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/Showcase.swift

@@ -0,0 +1,13 @@
+#if DEBUG
+import Foundation
+
+/// The App Store captures: launched with `-showcase`, the app skips the Apple
+/// sign-in and every read the captured screens make answers from fixtures here
+/// rather than from the server. Debug-only by construction: the Release archive
+/// compiles none of it. Grows with the app: each captured screen's data is added
+/// here, derived from one list so no screen contradicts another.
+enum Showcase {
+    static let isOn = ProcessInfo.processInfo.arguments.contains("-showcase")
+    static let firstName = "Ada"
+}
+#endif