Prep initial 0.1.0 release

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0]
+## [Unreleased]
+
+## [0.1.0] - 2024-09-06
 
 Initial Release

README.md

@@ -3,3 +3,29 @@
 # OAuth PKCE Flow for Kotlin Multiplatform (Android/iOS)
 
 A Kotlin Multiplatform library for Android and iOS that provides an [OAuth PKCE flow](https://oauth.net/2/pkce/) implementation.
+
+# Installation
+
+⚠️ This is a work-in-progress library that was recently extracted from
+a reference project. The API is subject to change. Detailed installation
+instructions need to be written.
+
+In general, the key steps for using this library are:
+
+ * Configure your iOS and Android apps to have a custom url app scheme (e.g. `exampleapp://`)
+ * Create an iOS and Android OAuth client on your server (we use [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper)) for the PKCE flow and Redirect URI. Configure your iOS and Android apps with the proper `client_id` values.
+ * In your shared view model, create/inject a [`PKCEFlow`](https://github.com/collectiveidea/oauth-kmp/blob/main/oauth-core/src/commonMain/kotlin/com/collectiveidea/oauth/PKCEFlow.kt).
+ * Collect the [`authState`](https://github.com/collectiveidea/oauth-kmp/blob/main/oauth-core/src/commonMain/kotlin/com/collectiveidea/oauth/PKCEFlow.kt#L60C16-L60C25) to be notified when the sign in process completes.
+ * Call [`startSignIn`](https://github.com/collectiveidea/oauth-kmp/blob/main/oauth-core/src/commonMain/kotlin/com/collectiveidea/oauth/PKCEFlow.kt#L100C16-L100C27) 
+   * On Android, in your main activity, override `onNewIntent` and handle the auth callback. Something like:
+    ```kotlin
+    override fun onNewIntent(intent: Intent) {
+        // Ensure the callbackUrl is for OAuth before processing it as such.
+        if (intent.data?.toString()?.startsWith(PKCE_REDIRECT_URL) == true) {
+            pkceFlow.continueSignInWithCallbackOrError(dataUrl, null)
+        }
+    }
+    ```
+   * On iOS, nothing else is needed. The [callback is automatically invoked](https://github.com/collectiveidea/oauth-kmp/blob/main/oauth-core/src/iosMain/kotlin/com/collectiveidea/oauth/IosPKCEFlow.kt#L26) by [`AuthenticationServices`](https://developer.apple.com/documentation/authenticationservices).
+ * When the [`authState.state`](https://github.com/collectiveidea/oauth-kmp/blob/main/oauth-core/src/commonMain/kotlin/com/collectiveidea/oauth/PKCEFlow.kt#L47) is `FINISHED`, either extract/save the tokens and proceed with sign-in, or present the user with an error message. See, e.g. https://github.com/collectiveidea/oauth-kmp/blob/main/oauth-core/src/commonTest/kotlin/com/collectiveidea/oauth/PKCEFlowTest.kt#L186
+

RELEASING.md

@@ -1,37 +1,30 @@
 # Releasing
 
-1. Update `version` in `gradle.properties` to the release version.
+1. Submit a PR with the following changes (see e.g. #4):
+   * Update `version` in `gradle.properties` to the release version.
+   * Update the `CHANGELOG.md`. Create a section for the new version and move the unreleased version there
+   * Update the `README.md` as necessary to reflect the new release version.
 
-2. Update the `CHANGELOG.md`.
-
-3. Update the `README.md` to reflect the new release version number.
-
-4. Commit
-
-   ```
-   $ git commit -am "Prepare version X.Y.Z"
-   ```
-
-5. Tag
+2. Once merged, pull latest into main locally. Tag version:
 
    ```
    $ git tag -am "Version X.Y.Z" X.Y.Z
    ```
 
-6. Push!
+3. Push tags:
 
    ```
-   $ git push && git push --tags
+   $ git push --tags
    ```
 
-7. Create GitHub Release
+4. Create GitHub Release
     1. Visit the [New Releases](https://github.com/collectiveidea/oauth-kmp/releases/new) page.
-    2. Supply release version and changelog
+    2. Supply release version and changelog link
 
-8. Publish (runtime)
+5. Publish
 
    ```
    $ ./gradlew publish
    ```
 
-9. Visit [Sonatype Nexus](https://s01.oss.sonatype.org) and promote the artifact.
+6. Visit [Sonatype Nexus](https://s01.oss.sonatype.org) and promote the artifact. (Close the staging repository, then Release it)

gradle.properties

@@ -11,5 +11,5 @@ android.useAndroidX=true
 android.nonTransitiveRClass=true
 
 #OAuth KMP
-version=0.1.0-SNAPSHOT
+version=0.1.0
 group=com.collectiveidea.oauth