docs: add Swift Logto core reference (#573)

* docs: add Swift Logto core reference

* fix: build

packages/docs/docs/sdk/README.md

@@ -0,0 +1 @@
+# Overview

packages/docs/docs/sdk/Swift/Logto/Enums/JwtField.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+---
+
+**ENUM**
+
+# `JwtField`
+
+```swift
+public enum JwtField
+```
+
+## Cases
+### `audience`
+
+```swift
+case audience
+```
+
+### `issuer`
+
+```swift
+case issuer
+```

packages/docs/docs/sdk/Swift/Logto/Enums/LogtoCore.md

@@ -0,0 +1,135 @@
+---
+sidebar_position: 2
+---
+
+**ENUM**
+
+# `LogtoCore`
+
+```swift
+public enum LogtoCore
+```
+
+## Structs
+###   [CodeTokenResponse](../Structs/LogtoCore.CodeTokenResponse.md)
+###   [OidcConfigResponse](../Structs/LogtoCore.OidcConfigResponse.md)
+###   [RefreshTokenTokenResponse](../Structs/LogtoCore.RefreshTokenTokenResponse.md)
+###   [UserInfoResponse](../Structs/LogtoCore.UserInfoResponse.md)
+
+## Properties
+### `postHeaders`
+
+```swift
+static let postHeaders: [String: String] = [
+    "Content-Type": "application/x-www-form-urlencoded",
+]
+```
+
+## Methods
+### `fetchOidcConfig(useSession:uri:)`
+
+```swift
+static func fetchOidcConfig(
+    useSession session: NetworkSession = URLSession.shared,
+    uri: URL
+) async throws -> OidcConfigResponse
+```
+
+### `fetchToken(useSession:byAuthorizationCode:codeVerifier:tokenEndpoint:clientId:redirectUri:)`
+
+```swift
+static func fetchToken(
+    useSession session: NetworkSession = URLSession.shared,
+    byAuthorizationCode code: String,
+    codeVerifier: String,
+    tokenEndpoint: String,
+    clientId: String,
+    redirectUri: String
+) async throws -> CodeTokenResponse
+```
+
+Fetch token by `authorization_code`.
+The returned `access_token` is only for user info enpoint.
+Note the function will NOT validate any token in the response.
+
+### `fetchToken(useSession:byRefreshToken:tokenEndpoint:clientId:resource:scopes:)`
+
+```swift
+static func fetchToken(
+    useSession session: NetworkSession = URLSession.shared,
+    byRefreshToken refreshToken: String,
+    tokenEndpoint: String,
+    clientId: String,
+    resource: String?,
+    scopes: [String]
+) async throws -> RefreshTokenTokenResponse
+```
+
+Fetch token by `refresh_token`.
+Note the function will NOT validate any token in the response.
+
+### `fetchUserInfo(useSession:userInfoEndpoint:accessToken:)`
+
+```swift
+static func fetchUserInfo(
+    useSession session: NetworkSession = URLSession.shared,
+    userInfoEndpoint: String,
+    accessToken: String
+) async throws -> UserInfoResponse
+```
+
+### `fetchJwkSet(useSession:jwksUri:)`
+
+```swift
+static func fetchJwkSet(
+    useSession session: NetworkSession = URLSession.shared,
+    jwksUri: String
+) async throws -> JWKSet
+```
+
+### `generateSignInUri(authorizationEndpoint:clientId:redirectUri:codeChallenge:state:scopes:resources:)`
+
+```swift
+static func generateSignInUri(
+    authorizationEndpoint: String,
+    clientId: String,
+    redirectUri: URL,
+    codeChallenge: String,
+    state: String,
+    scopes: [String] = [],
+    resources: [String] = []
+) throws -> URL
+```
+
+### `generateSignOutUri(endSessionEndpoint:idToken:postLogoutRedirectUri:)`
+
+```swift
+static func generateSignOutUri(
+    endSessionEndpoint: String,
+    idToken: String,
+    postLogoutRedirectUri: String?
+) throws -> URL
+```
+
+### `revoke(useSession:token:revocationEndpoint:clientId:)`
+
+```swift
+static func revoke(
+    useSession session: NetworkSession = URLSession.shared,
+    token: String,
+    revocationEndpoint: String,
+    clientId: String
+) async throws
+```
+
+### `verifyAndParseSignInCallbackUri(_:redirectUri:state:)`
+
+```swift
+static func verifyAndParseSignInCallbackUri(
+    _ callbackUri: URL,
+    redirectUri: URL,
+    state: String
+) throws -> String
+```
+
+Verify the given `callbackUri` matches the requirements and return `code` parameter if success.

packages/docs/docs/sdk/Swift/Logto/Enums/LogtoErrors.Response.md

@@ -0,0 +1,20 @@
+**ENUM**
+
+# `LogtoErrors.Response`
+
+```swift
+public enum Response: LocalizedError, Equatable
+```
+
+## Cases
+### `notHttpResponse(response:)`
+
+```swift
+case notHttpResponse(response: URLResponse?)
+```
+
+### `withCode(code:httpResponse:data:)`
+
+```swift
+case withCode(code: Int, httpResponse: HTTPURLResponse, data: Data?)
+```

packages/docs/docs/sdk/Swift/Logto/Enums/LogtoErrors.UriVerification.md

@@ -0,0 +1,38 @@
+**ENUM**
+
+# `LogtoErrors.UriVerification`
+
+```swift
+public enum UriVerification: LocalizedError, Equatable
+```
+
+## Cases
+### `redirectUriMismatched`
+
+```swift
+case redirectUriMismatched
+```
+
+### `decodeComponentsFailed`
+
+```swift
+case decodeComponentsFailed
+```
+
+### `stateMismatched`
+
+```swift
+case stateMismatched
+```
+
+### `errorItemFound(items:)`
+
+```swift
+case errorItemFound(items: [URLQueryItem])
+```
+
+### `missingCode`
+
+```swift
+case missingCode
+```

packages/docs/docs/sdk/Swift/Logto/Enums/LogtoErrors.UrlConstruction.md

@@ -0,0 +1,20 @@
+**ENUM**
+
+# `LogtoErrors.UrlConstruction`
+
+```swift
+public enum UrlConstruction: LocalizedError, Equatable
+```
+
+## Cases
+### `invalidEndpoint`
+
+```swift
+case invalidEndpoint
+```
+
+### `unableToConstructUrl`
+
+```swift
+case unableToConstructUrl
+```

packages/docs/docs/sdk/Swift/Logto/Enums/LogtoErrors.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 3
+---
+**ENUM**
+
+# `LogtoErrors`
+
+```swift
+public enum LogtoErrors
+```
+
+## Enums
+
+###   [Response](LogtoErrors.Response.md)
+###   [UriVerification](LogtoErrors.UriVerification.md)
+###   [UrlConstruction](LogtoErrors.UrlConstruction.md)

packages/docs/docs/sdk/Swift/Logto/Enums/LogtoRequest.HttpMethod.md

@@ -0,0 +1,20 @@
+**ENUM**
+
+# `LogtoRequest.HttpMethod`
+
+```swift
+public enum HttpMethod: String
+```
+
+## Cases
+### `get`
+
+```swift
+case get = "GET"
+```
+
+### `post`
+
+```swift
+case post = "POST"
+```

packages/docs/docs/sdk/Swift/Logto/Enums/LogtoRequest.md

@@ -0,0 +1,77 @@
+**ENUM**
+
+# `LogtoRequest`
+
+```swift
+public enum LogtoRequest
+```
+
+## Enums
+###   [LogtoRequest.HttpMethod](LogtoRequest.HttpMethod.md)
+
+## Methods
+### `load(useSession:method:url:headers:body:)`
+
+```swift
+public static func load(
+    useSession session: NetworkSession,
+    method: HttpMethod,
+    url: URL,
+    headers: [String: String] = [:],
+    body: Data? = nil
+) async -> (Data?, Error?)
+```
+
+### `load(useSession:method:endpoint:headers:body:)`
+
+```swift
+public static func load(
+    useSession session: NetworkSession,
+    method: HttpMethod,
+    endpoint: String,
+    headers: [String: String] = [:],
+    body: Data? = nil
+) async -> (Data?, Error?)
+```
+
+### `get(useSession:endpoint:headers:)`
+
+```swift
+public static func get<T: Codable>(
+    useSession session: NetworkSession,
+    endpoint: String,
+    headers: [String: String] = [:]
+) async throws -> T
+```
+
+### `get(useSession:url:headers:)`
+
+```swift
+public static func get<T: Codable>(
+    useSession session: NetworkSession,
+    url: URL,
+    headers: [String: String] = [:]
+) async throws -> T
+```
+
+### `post(useSession:endpoint:headers:body:)`
+
+```swift
+public static func post<T: Codable>(
+    useSession session: NetworkSession,
+    endpoint: String,
+    headers: [String: String] = [:],
+    body: Data? = nil
+) async throws -> T
+```
+
+### `post(useSession:endpoint:headers:body:)`
+
+```swift
+public static func post(
+    useSession session: NetworkSession,
+    endpoint: String,
+    headers: [String: String] = [:],
+    body: Data? = nil
+) async throws
+```

packages/docs/docs/sdk/Swift/Logto/Enums/LogtoUtilities.md

@@ -0,0 +1,67 @@
+**ENUM**
+
+# `LogtoUtilities`
+
+```swift
+public enum LogtoUtilities
+```
+
+## Methods
+### `withReservedScopes(_:)`
+
+```swift
+public static func withReservedScopes(_ scopes: [String]) -> [String]
+```
+
+### `generateState()`
+
+```swift
+public static func generateState() -> String
+```
+
+### `generateCodeVerifier()`
+
+```swift
+public static func generateCodeVerifier() -> String
+```
+
+### `generateCodeChallenge(codeVerifier:)`
+
+```swift
+public static func generateCodeChallenge(codeVerifier: String) -> String
+```
+
+### `decodeIdToken(_:)`
+
+```swift
+static func decodeIdToken(_ idToken: String) throws -> IdTokenClaims
+```
+
+Decode ID Token claims WITHOUT validation.
+- Parameter token: The JWT to decode
+- Returns: A set of ID Token claims
+
+#### Parameters
+
+| Name | Description |
+| ---- | ----------- |
+| token | The JWT to decode |
+
+### `verifyIdToken(_:issuer:clientId:jwks:forTimeInterval:)`
+
+```swift
+static func verifyIdToken(
+    _ idToken: String,
+    issuer: String,
+    clientId: String,
+    jwks: JWKSet,
+    forTimeInterval: TimeInterval = Date().timeIntervalSince1970
+) throws
+```
+
+Verify the give ID Token:
+* One of the JWKs matches the token.
+* Issuer matches token payload `iss`.
+* Client ID matches token payload `aud`.
+* The token is not expired.
+* The token is issued in +/- 1min.

packages/docs/docs/sdk/Swift/Logto/Enums/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 1
+}

packages/docs/docs/sdk/Swift/Logto/Extensions/URLSession.md

@@ -0,0 +1,13 @@
+**EXTENSION**
+
+# `URLSession`
+```swift
+extension URLSession: NetworkSession
+```
+
+## Methods
+### `loadData(with:)`
+
+```swift
+public func loadData(with request: URLRequest) async -> (Data?, Error?)
+```

packages/docs/docs/sdk/Swift/Logto/Extensions/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 4
+}

packages/docs/docs/sdk/Swift/Logto/Protocols/NetworkSession.md

@@ -0,0 +1,14 @@
+**PROTOCOL**
+
+# `NetworkSession`
+
+```swift
+public protocol NetworkSession
+```
+
+## Methods
+### `loadData(with:)`
+
+```swift
+func loadData(with request: URLRequest) async -> (Data?, Error?)
+```

packages/docs/docs/sdk/Swift/Logto/Protocols/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 3
+}

packages/docs/docs/sdk/Swift/Logto/README.md

@@ -0,0 +1,32 @@
+# Logto Module
+
+## Structs
+
+-   [IdTokenClaims](Structs/IdTokenClaims.md)
+-   [JwtHeader](Structs/JwtHeader.md)
+-   [LogtoCore.CodeTokenResponse](Structs/LogtoCore.CodeTokenResponse.md)
+-   [LogtoCore.OidcConfigResponse](Structs/LogtoCore.OidcConfigResponse.md)
+-   [LogtoCore.RefreshTokenTokenResponse](Structs/LogtoCore.RefreshTokenTokenResponse.md)
+-   [LogtoCore.UserInfoResponse](Structs/LogtoCore.UserInfoResponse.md)
+
+## Enums
+
+-   [JwtField](Enums/JwtField.md)
+-   [LogtoCore](Enums/LogtoCore.md)
+-   [LogtoErrors](Enums/LogtoErrors.md)
+-   [LogtoErrors.Response](Enums/LogtoErrors.Response.md)
+-   [LogtoErrors.UriVerification](Enums/LogtoErrors.UriVerification.md)
+-   [LogtoErrors.UrlConstruction](Enums/LogtoErrors.UrlConstruction.md)
+-   [LogtoRequest](Enums/LogtoRequest.md)
+-   [LogtoRequest.HttpMethod](Enums/LogtoRequest.HttpMethod.md)
+-   [LogtoUtilities](Enums/LogtoUtilities.md)
+
+## Protocols
+
+-   [NetworkSession](Protocols/NetworkSession.md)
+
+## Extensions
+
+-   [URLSession](Extensions/URLSession.md)
+
+This file was originally generated by [SourceDocs](https://github.com/eneko/SourceDocs)

packages/docs/docs/sdk/Swift/Logto/Structs/IdTokenClaims.md

@@ -0,0 +1,44 @@
+**STRUCT**
+
+# `IdTokenClaims`
+
+```swift
+public struct IdTokenClaims: Codable, Equatable
+```
+
+## Properties
+### `sub`
+
+```swift
+public let sub: String
+```
+
+### `atHash`
+
+```swift
+public let atHash: String?
+```
+
+### `aud`
+
+```swift
+public let aud: String
+```
+
+### `exp`
+
+```swift
+public let exp: Int64
+```
+
+### `iat`
+
+```swift
+public let iat: Int64
+```
+
+### `iss`
+
+```swift
+public let iss: String
+```

packages/docs/docs/sdk/Swift/Logto/Structs/JwtHeader.md

@@ -0,0 +1,20 @@
+**STRUCT**
+
+# `JwtHeader`
+
+```swift
+public struct JwtHeader: Codable
+```
+
+## Properties
+### `alg`
+
+```swift
+public let alg: SignatureAlgorithm
+```
+
+### `typ`
+
+```swift
+public let typ: TokenType
+```

packages/docs/docs/sdk/Swift/Logto/Structs/LogtoCore.CodeTokenResponse.md

@@ -0,0 +1,38 @@
+**STRUCT**
+
+# `LogtoCore.CodeTokenResponse`
+
+```swift
+struct CodeTokenResponse: Codable, Equatable
+```
+
+## Properties
+### `accessToken`
+
+```swift
+public let accessToken: String
+```
+
+### `refreshToken`
+
+```swift
+public let refreshToken: String
+```
+
+### `idToken`
+
+```swift
+public let idToken: String
+```
+
+### `scope`
+
+```swift
+public let scope: String
+```
+
+### `expiresIn`
+
+```swift
+public let expiresIn: Int64
+```

packages/docs/docs/sdk/Swift/Logto/Structs/LogtoCore.OidcConfigResponse.md

@@ -0,0 +1,50 @@
+**STRUCT**
+
+# `LogtoCore.OidcConfigResponse`
+
+```swift
+struct OidcConfigResponse: Codable, Equatable
+```
+
+## Properties
+### `authorizationEndpoint`
+
+```swift
+public let authorizationEndpoint: String
+```
+
+### `tokenEndpoint`
+
+```swift
+public let tokenEndpoint: String
+```
+
+### `endSessionEndpoint`
+
+```swift
+public let endSessionEndpoint: String
+```
+
+### `revocationEndpoint`
+
+```swift
+public let revocationEndpoint: String
+```
+
+### `userinfoEndpoint`
+
+```swift
+public let userinfoEndpoint: String
+```
+
+### `jwksUri`
+
+```swift
+public let jwksUri: String
+```
+
+### `issuer`
+
+```swift
+public let issuer: String
+```

packages/docs/docs/sdk/Swift/Logto/Structs/LogtoCore.RefreshTokenTokenResponse.md

@@ -0,0 +1,38 @@
+**STRUCT**
+
+# `LogtoCore.RefreshTokenTokenResponse`
+
+```swift
+struct RefreshTokenTokenResponse: Codable, Equatable
+```
+
+## Properties
+### `accessToken`
+
+```swift
+public let accessToken: String
+```
+
+### `refreshToken`
+
+```swift
+public let refreshToken: String
+```
+
+### `idToken`
+
+```swift
+public let idToken: String?
+```
+
+### `scope`
+
+```swift
+public let scope: String
+```
+
+### `expiresIn`
+
+```swift
+public let expiresIn: Int64
+```

packages/docs/docs/sdk/Swift/Logto/Structs/LogtoCore.UserInfoResponse.md

@@ -0,0 +1,14 @@
+**STRUCT**
+
+# `LogtoCore.UserInfoResponse`
+
+```swift
+struct UserInfoResponse: Codable, Equatable
+```
+
+## Properties
+### `sub`
+
+```swift
+public let sub: String
+```

packages/docs/docs/sdk/Swift/Logto/Structs/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 2
+}

packages/docs/docs/sdk/Swift/README.md

@@ -0,0 +1 @@
+# Swift SDK Reference

packages/docs/docusaurus.config.js

@@ -27,6 +27,7 @@ const config = {
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
+          breadcrumbs: false,
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
           editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
@@ -50,10 +51,16 @@ const config = {
         items: [
           {
             type: 'doc',
-            docId: 'intro',
+            docId: 'tutorial/README',
             position: 'left',
             label: 'Tutorial',
           },
+          {
+            type: 'doc',
+            docId: 'sdk/README',
+            position: 'left',
+            label: 'SDK',
+          },
           {
             type: 'localeDropdown',
             position: 'right',
@@ -73,7 +80,7 @@ const config = {
             items: [
               {
                 label: 'Tutorial',
-                to: '/docs/intro',
+                to: '/docs/tutorial',
               },
             ],
           },
@@ -97,6 +104,7 @@ const config = {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
+        additionalLanguages: ['swift'],
       },
     }),
 };

packages/docs/sidebars.js

@@ -14,7 +14,8 @@
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+  tutorialSidebar: [{type: 'autogenerated', dirName: 'tutorial'}],
+  sdkSidebar: [{type: 'autogenerated', dirName: 'sdk'}],
 
   // But you can create a sidebar manually
   /*

packages/docs/src/pages/index.tsx

@@ -16,7 +16,7 @@ function HomepageHeader() {
         <div className={styles.buttons}>
           <Link
             className="button button--secondary button--lg"
-            to="/docs/intro">
+            to="/docs/tutorial">
             Docusaurus Tutorial - 5min ⏱️
           </Link>
         </div>