Documentation

Sources/OAuthKit/OAuthKit.docc/Configuration.md

@@ -0,0 +1,81 @@
+# OAuthKit Configuration
+
+Explore advanced OAuth configuration options such as Keychain protection and private browsing.
+
+@Metadata {
+    @PageKind(article)
+    @PageColor(red)
+    @Available(iOS, introduced: "18.0")
+    @Available(macOS, introduced: "15.0")
+    @Available(tvOS, introduced: "18.0")
+    @Available(visionOS, introduced: "2.0")
+    @Available(watchOS, introduced: "11.0")
+}
+
+## Overview
+
+Both of the ``OAuth`` initializers ``OAuth/init(providers:options:)`` and ``OAuth/init(_:options:)`` accept a dictionary of `[OAuth.Option:Any]` which can be used to configure the loading and runtime options.
+
+### Application Tag
+The ``OAuth/Option/applicationTag`` option is used to create unique keys for access tokens that are stored inside the Keychain. Typically, an app would set this value to be the same as their Bundle identifier. 
+
+```swift
+let options: [OAuth.Option: Any] = [
+    .applicationTag: "com.oauthkit.Sampler",
+]
+let oauth: OAuth = .init(.main, options: options)
+```
+
+### Auto Refresh
+The ``OAuth/Option/autoRefresh`` option is used to determine if tokens should be auto refreshed when they expire or not. This value is true by default. 
+
+```swift
+let options: [OAuth.Option: Any] = [
+    .autoRefresh: false,
+]
+let oauth: OAuth = .init(.main, options: options)
+```
+
+### URL Session
+The ``OAuth/Option/urlSession`` option is used to pass in a custom URLSession that will be used by your ``OAuth`` object to support any custom protocols or URL schemes that your app supports.This allows developers to register any custom URLProtocol classes that can handle the loading of protocol-specific URL data.
+
+```swift
+// Custom URLSession
+let configuration: URLSessionConfiguration = .ephemeral
+configuration.protocolClasses = [CustomURLProtocol.self]
+let urlSession: URLSession = .init(configuration: configuration)
+
+let options: [OAuth.Option: Any] = [.urlSession: urlSession]
+```
+
+### Private Browsing
+The ``OAuth/Option/useNonPersistentWebDataStore`` option allows developers to implement private browsing inside the ``OAWebView``. Setting this value to true forces the ``OAWebView`` to use a non-persistent data store, preventing data from being written to the file system.
+
+```swift
+let options: [OAuth.Option: Any] = [
+    .useNonPersistentWebDataStore: true,
+]
+let oauth: OAuth = .init(.module, options: options)
+```
+
+### Keychain Protection
+The ``OAuth/Option/requireAuthenticationWithBiometricsOrCompanion`` option allows you to protect access to your keychain items with biometrics until successful local authentication. If the ``OAuth/Option/requireAuthenticationWithBiometricsOrCompanion`` option is set to true, the device owner will need to be authenticated by biometry or a companion device before keychain items (tokens) can be accessed. OAuthKit uses a default LAContext, but if you need fine-grained control while evaluating a user’s identity, pass your own custom LAContext to the options via the ``OAuth/Option/localAuthentication`` option.
+
+```swift
+// Custom LAContext
+let localAuthentication: LAContext = .init()
+localAuthentication.localizedReason = "read tokens from keychain"
+localAuthentication.localizedFallbackTitle = "Use password"
+localAuthentication.touchIDAuthenticationAllowableReuseDuration = 10
+
+let options: [OAuth.Option: Any] = [
+    .localAuthentication: localAuthentication,
+    .requireAuthenticationWithBiometricsOrCompanion: true
+]
+let oauth: OAuth = .init(.module, options: options)
+```
+
+> Important: The ``OAuth/Option/requireAuthenticationWithBiometricsOrCompanion`` is only available on iOS, macOS, and visionOS.
+
+> Tip: See ``OAuth/Option`` for a complete list of configuration options.
+

Sources/OAuthKit/OAuthKit.docc/Extensions/EnvironmentValues.md

@@ -0,0 +1,9 @@
+# ``OAuthKit/SwiftUICore/EnvironmentValues``
+@Metadata {
+    @Available(iOS, introduced: "18.0")
+    @Available(macOS, introduced: "15.0")
+    @Available(tvOS, introduced: "18.0")
+    @Available(visionOS, introduced: "2.0")
+    @Available(watchOS, introduced: "11.0")
+}
+

Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebView.md

@@ -0,0 +1,10 @@
+# ``OAuthKit/OAWebView``
+@Metadata {
+    @Available(iOS, introduced: "18.0")
+    @Available(macOS, introduced: "15.0")
+    @Available(visionOS, introduced: "2.0")
+}
+
+> Important: The ``OAWebView`` is only available for Apple operating systems with browsers. If you want to start
+an ``OAuth/authorize(provider:grantType:)`` flow on tvOS or watchOS, be sure to use the 
+``OAuth/GrantType/deviceCode`` grant Type. See <doc:GettingStarted> for more details.

Sources/OAuthKit/OAuthKit.docc/Extensions/OAWebViewCoordinator.md

@@ -0,0 +1,10 @@
+# ``OAuthKit/OAWebViewCoordinator``
+@Metadata {
+    @Available(iOS, introduced: "18.0")
+    @Available(macOS, introduced: "15.0")
+    @Available(visionOS, introduced: "2.0")
+}
+
+> Important: The ``OAWebViewCoordinator`` is only available for Apple operating systems with browsers. If you want to start
+an ``OAuth/authorize(provider:grantType:)`` flow on tvOS or watchOS, be sure to use the 
+``OAuth/GrantType/deviceCode`` grant Type. See <doc:GettingStarted> for more details.

Sources/OAuthKit/OAuthKit.docc/GettingStarted.md

@@ -1,9 +1,10 @@
 # Getting Started with OAuthKit
 
-Create an ``OAuth`` instance and start an authorization flow.
+Learn how to create an observable OAuth instance and start an authorization flow.
 
 @Metadata {
     @PageKind(article)
+    @PageColor(yellow)
     @Available(iOS, introduced: "18.0")
     @Available(macOS, introduced: "15.0")
     @Available(tvOS, introduced: "18.0")

Sources/OAuthKit/OAuthKit.docc/OAuthKit.md

@@ -17,10 +17,16 @@ OAuthKit offers a robust, type-safe, and performant OAuth 2.0 implementation usi
 
 This has the advantage of avoiding direct coupling with an authorization flow, enabling highly flexible and fine-grained control when interacting with an ``OAuth/Provider``. It also allows updates across multiple observers.
 
-### Featured
+### Articles
 
 @Links(visualStyle: detailedGrid) {
     - <doc:GettingStarted>
+    - <doc:Configuration>
+}
+
+### Sample code
+
+@Links(visualStyle: detailedGrid) {
     - <doc:SampleCode>
 }
 

Sources/OAuthKit/OAuthKit.docc/SampleCode.md

@@ -1,4 +1,4 @@
-# OAuthKit Sample: Integrating OAuthKit into an App
+# OAuthSample: Integrating OAuthKit into an App
 
 Integrate OAuthKit into a multiplatform app with support for iOS, macOS, tvOS, visionOS, and watchOS.
 

Sources/OAuthKit/Views/OAWebView.swift

@@ -17,7 +17,7 @@ public struct OAWebView {
     let oauth: OAuth
     let view: WKWebView
 
-    /// Initializer with the speciifed oauth object,
+    /// Initializer with the speciifed oauth object.
     /// - Parameter oauth: the oauth object to use
     public init(oauth: OAuth) {
         self.oauth = oauth