Add documentation and enhance Firebase Auth error handling

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: ci
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '9.0.x'
+      - name: Restore Auth (net9.0 only)
+        run: dotnet restore src/Auth/Auth.csproj -p:TargetFramework=net9.0
+      - name: Restore unit tests (net9.0 only)
+        run: dotnet restore tests/Plugin.Firebase.UnitTests/Plugin.Firebase.UnitTests.csproj -p:TargetFramework=net9.0
+      - name: Build Auth (net9.0 only)
+        run: dotnet build src/Auth/Auth.csproj -c Release -f net9.0 --no-restore
+      - name: Build unit tests
+        run: dotnet build tests/Plugin.Firebase.UnitTests/Plugin.Firebase.UnitTests.csproj -c Release --no-restore
+      - name: Run unit tests
+        run: dotnet test tests/Plugin.Firebase.UnitTests/Plugin.Firebase.UnitTests.csproj -c Release --no-build --no-restore

.github/workflows/publish-github-packages.yml

@@ -0,0 +1,69 @@
+name: publish-github-packages
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  pack-and-publish:
+    runs-on: macos-latest
+    env:
+      DOTNET_MULTILEVEL_LOOKUP: 0
+      DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+      DOTNET_CLI_TELEMETRY_OPTOUT: 1
+      DOTNET_NOLOGO: true
+      DOTNET_CLI_WORKLOAD_UPDATE_NOTIFICATION_LEVEL: Disable
+    strategy:
+      matrix:
+        project:
+          - src/Analytics/Analytics.csproj
+          - src/Auth/Auth.csproj
+          - src/CloudMessaging/CloudMessaging.csproj
+          - src/Core/Core.csproj
+          - src/Crashlytics/Crashlytics.csproj
+          - src/Firestore/Firestore.csproj
+          - src/Functions/Functions.csproj
+          - src/RemoteConfig/RemoteConfig.csproj
+          - src/Storage/Storage.csproj
+          - src/Bundled/Bundled.csproj
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Determine package version
+        id: version
+        shell: bash
+        run: |
+          if [[ "${{ github.ref }}" =~ ^refs/tags/v ]]; then
+            REF="${{ github.ref }}"
+            VERSION="${REF#refs/tags/v}"
+          else
+            CSPROJ="src/Core/Core.csproj"
+            BASE_VERSION=$(grep -oE '<PackageVersion>[^<]+' "$CSPROJ" | head -n 1 | sed 's/<PackageVersion>//' || echo "0.1.0")
+            COMMIT_SHORT=$(git rev-parse --short HEAD)
+            RUN_NUMBER="${{ github.run_number }}"
+            VERSION="${BASE_VERSION}-prerelease.${RUN_NUMBER}.${COMMIT_SHORT}"
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Package version: ${VERSION}"
+
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '9.0.x'
+      - name: Install workloads
+        shell: bash
+        run: |
+          dotnet workload install ios android
+      - name: Restore
+        run: dotnet restore ${{ matrix.project }}
+      - name: Pack
+        run: dotnet pack ${{ matrix.project }} -c Release -o artifacts --no-restore /p:PackageVersion="${{ steps.version.outputs.version }}"
+      - name: Push to GitHub Packages
+        run: dotnet nuget push "artifacts/*.nupkg" --source "https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json" --api-key "${{ secrets.GITHUB_TOKEN }}" --skip-duplicate

.github/workflows/sample-android.yml

@@ -0,0 +1,26 @@
+name: sample-android (manual)
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build_sample_android:
+    runs-on: ubuntu-latest
+    env:
+      DOTNET_MULTILEVEL_LOOKUP: 0
+      DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+      DOTNET_CLI_TELEMETRY_OPTOUT: 1
+      DOTNET_NOLOGO: true
+      DOTNET_CLI_WORKLOAD_UPDATE_NOTIFICATION_LEVEL: Disable
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '9.0.x'
+      - name: Install Android workload
+        run: dotnet workload install android
+      - name: Build Playground (Android)
+        run: dotnet build sample/Playground/Playground.csproj -c Debug -f net9.0-android

.github/workflows/sample-ios.yml

@@ -0,0 +1,31 @@
+name: sample-ios (manual)
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build_sample_ios:
+    runs-on: macos-latest
+    env:
+      DOTNET_MULTILEVEL_LOOKUP: 0
+      DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+      DOTNET_CLI_TELEMETRY_OPTOUT: 1
+      DOTNET_NOLOGO: true
+      DOTNET_CLI_WORKLOAD_UPDATE_NOTIFICATION_LEVEL: Disable
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '9.0.x'
+      - name: Install iOS workload
+        run: dotnet workload install ios
+      - name: Build Playground (iOS simulator, no signing)
+        run: |
+          dotnet build sample/Playground/Playground.csproj \
+            -c Debug \
+            -f net9.0-ios \
+            -p:RuntimeIdentifier=iossimulator-arm64 \
+            -p:EnableCodeSigning=false

AGENTS.md

@@ -0,0 +1,34 @@
+# Plugin.Firebase — AI Collaboration Guide
+
+This repository is public open source. Keep all contributions generic and reusable.
+Do **not** include private app details, proprietary business context, or secrets.
+
+## Repository map
+- `src/`: Package implementations (multi-targeted `net9.0`, `net9.0-android`, `net9.0-ios`)
+- `docs/`: Feature docs and setup guides
+- `sample/`: MAUI sample app
+- `tests/`: Integration test harness (runs on device)
+
+## Guardrails
+- Follow `.editorconfig` formatting rules.
+- Run `dotnet format Plugin.Firebase.sln` before PRs.
+- Avoid committing secrets (Firebase config files, signing keys, tokens).
+- Keep changes minimal and scoped; update docs when behavior changes.
+- Do not introduce app-specific assumptions.
+
+## Build & test (quick)
+- Restore: `dotnet restore Plugin.Firebase.sln`
+- Build (all TFMs): `dotnet build Plugin.Firebase.sln -c Release`
+- Build only `net9.0` (no mobile workloads): `dotnet build src/Auth/Auth.csproj -c Release -f net9.0`
+- Unit tests: `dotnet test tests/Plugin.Firebase.UnitTests/Plugin.Firebase.UnitTests.csproj`
+- Integration tests are device-only. See `BUILDING.md`.
+
+## Packaging & CI
+- Packaging guidelines: `docs/packaging-github-packages.md`
+- CI guidance: `docs/ci-cd.md`
+- Workflows: `.github/workflows/ci.yml`, `.github/workflows/publish-github-packages.yml`
+
+## AI workflow
+1) Read the relevant docs in `docs/` plus the target feature area in `src/`.
+2) Propose a small, verifiable change set before editing code.
+3) Keep public API changes explicit and documented.

BUILDING.md

@@ -0,0 +1,43 @@
+# Building Plugin.Firebase
+
+## Prerequisites
+- .NET SDK version matching `global.json`
+- Android workload (for `net9.0-android`)
+- iOS workload + Xcode (for `net9.0-ios`, macOS only)
+
+Install workloads (if needed):
+```
+dotnet workload install android ios
+```
+
+## Restore & build
+```
+dotnet restore Plugin.Firebase.sln
+dotnet build Plugin.Firebase.sln -c Release
+```
+
+Note: building the full solution includes the sample and integration test apps.
+Running those apps requires `GoogleService-Info.plist` and `google-services.json` files (not committed).
+If you don’t have local Firebase configs, use the `net9.0` build below to validate the packages.
+
+### Build without mobile workloads
+If you want to validate core code without Android/iOS toolchains:
+```
+dotnet build src/Auth/Auth.csproj -c Release -f net9.0
+```
+
+## Tests (integration)
+Tests live under `tests/Plugin.Firebase.IntegrationTests` and run on a real device.
+You must supply your own Firebase config files (not committed):
+- `GoogleService-Info.plist` (iOS)
+- `google-services.json` (Android)
+
+Run:
+```
+dotnet test tests/Plugin.Firebase.IntegrationTests/Plugin.Firebase.IntegrationTests.csproj --no-build
+```
+
+## Formatting
+```
+dotnet format Plugin.Firebase.sln
+```

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to Plugin.Firebase
+
+Thanks for contributing! This repo is public OSS. Please keep contributions general and reusable.
+
+## Quick start
+1) Fork the repo and create a feature branch.
+2) Make focused changes.
+3) Run formatting and relevant builds.
+4) Open a PR with a clear description.
+
+## Development guidelines
+- Follow `.editorconfig` rules.
+- Format code before PRs: `dotnet format Plugin.Firebase.sln`
+- Avoid app-specific or proprietary context in code/docs.
+- Never commit secrets (Firebase configs, signing keys, tokens).
+- Keep API changes backward-compatible when possible.
+
+## Versioning
+Package versions are defined per project (`src/*/*.csproj` as `PackageVersion`).
+If you change package APIs, ensure the version bump is consistent across affected packages.
+
+### Release process (recommended)
+This repo uses lockstep package versioning (all `src/*/*.csproj` share the same `PackageVersion`).
+
+When preparing a release:
+1) Bump `PackageVersion` in **all** projects under `src/*/*.csproj`.
+   - Use **patch** (`4.0.0` → `4.0.1`) for bugfixes and backward-compatible improvements.
+   - Use **minor** (`4.0.0` → `4.1.0`) for backward-compatible feature additions.
+   - Use **major** (`4.x` → `5.0.0`) for breaking changes.
+2) Update release notes in the relevant docs under `docs/` (e.g. `docs/auth.md`).
+3) Merge to `develop`, then push a tag `vX.Y.Z` to trigger publishing to GitHub Packages.
+
+Notes:
+- The publish workflow derives the NuGet package version from the `vX.Y.Z` tag, so tags should match `PackageVersion`.
+- For manual prerelease runs, use the workflow's `workflow_dispatch` trigger.
+
+## Testing
+Integration tests require a real device and local Firebase config files.
+See `BUILDING.md` for setup and test commands.
+
+## Formatting only modified files
+Format all files changed on the current branch (compared to `origin/master`):
+```
+dotnet format Plugin.Firebase.sln --include $(git diff --name-only origin/master...HEAD)
+```
+
+Format only staged files (not yet committed):
+```
+dotnet format Plugin.Firebase.sln --include $(git diff --name-only --cached)
+```
+
+## Documentation
+If you change behavior or APIs, update the relevant docs in `docs/` and/or `README.md`.

Plugin.Firebase.sln

@@ -8,6 +8,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Storage", "src\Storage\Stor
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Plugin.Firebase.IntegrationTests", "tests\Plugin.Firebase.IntegrationTests\Plugin.Firebase.IntegrationTests.csproj", "{9426163C-B64D-4079-8C79-2E7D3C1105A1}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Plugin.Firebase.UnitTests", "tests\Plugin.Firebase.UnitTests\Plugin.Firebase.UnitTests.csproj", "{8C2C6C9C-9A4B-4A93-9C6D-8B4E6D36F2B7}"
+EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Features", "Features", "{FD5845E5-6DE7-456C-AEF3-FCF0F678B7AB}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Playground", "sample\Playground\Playground.csproj", "{69175BBF-DEAF-4CB3-AF0B-913C67B5F1CF}"
@@ -53,6 +55,10 @@ Global
 		{9426163C-B64D-4079-8C79-2E7D3C1105A1}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{9426163C-B64D-4079-8C79-2E7D3C1105A1}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{9426163C-B64D-4079-8C79-2E7D3C1105A1}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8C2C6C9C-9A4B-4A93-9C6D-8B4E6D36F2B7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8C2C6C9C-9A4B-4A93-9C6D-8B4E6D36F2B7}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8C2C6C9C-9A4B-4A93-9C6D-8B4E6D36F2B7}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8C2C6C9C-9A4B-4A93-9C6D-8B4E6D36F2B7}.Release|Any CPU.Build.0 = Release|Any CPU
 		{69175BBF-DEAF-4CB3-AF0B-913C67B5F1CF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{69175BBF-DEAF-4CB3-AF0B-913C67B5F1CF}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{69175BBF-DEAF-4CB3-AF0B-913C67B5F1CF}.Release|Any CPU.ActiveCfg = Release|Any CPU

README.md

@@ -182,7 +182,7 @@ Visual Studio and Windows both have issues with long paths. The issue is explain
 
 ## Contributions
 
-You are welcome to contribute to this project by creating a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). The project contains an .editorconfig file that handles the code formatting, so please apply the formatting rules by running `dotnet format src/Plugin.Firebase.sln` in the console before creating a Pull Request (see [dotnet-format docs](https://github.com/dotnet/format) or [this video](https://www.youtube.com/watch?v=lGvP9SZ98vM&t) for more information).
+You are welcome to contribute to this project by creating a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). See `CONTRIBUTING.md` and `BUILDING.md` for contribution and build guidance. The project contains an .editorconfig file that handles the code formatting, so please apply the formatting rules by running `dotnet format Plugin.Firebase.sln` in the console before creating a Pull Request (see [dotnet-format docs](https://github.com/dotnet/format) or [this video](https://www.youtube.com/watch?v=lGvP9SZ98vM&t) for more information).
 
 ## License
 

docs/auth.md

@@ -53,7 +53,7 @@ You can use [Firebase Authentication](https://firebase.google.com/docs/auth) to
 
 ![firestore_poco.png](../art/project_settings_sha1.png)
 - Call `FirebaseAuthImplementation.HandleActivityResultAsync(requestCode, resultCode, data);` from `MainActivity.OnActivityResult(...)`
-- If you are on version 2.0.5 or later, add the following package to your project's `.csproj` file to prevent build errors:
+- If you are on version 2.0.5 or later, you may want add the following package to your project's `.csproj` file to prevent build errors:
 ```xml
   <PackageReference Include="Xamarin.AndroidX.Browser" Version="1.6.0.2" />
 ```
@@ -70,7 +70,24 @@ Since code should be documenting itself you can also take a look at the followin
 - [tests/.../AuthFixture.cs](https://github.com/TobiasBuchholz/Plugin.Firebase/blob/master/tests/Plugin.Firebase.IntegrationTests/Auth/AuthFixture.cs)
 - [sample/.../AuthService.cs](https://github.com/TobiasBuchholz/Plugin.Firebase/blob/master/sample/Playground/Common/Services/Auth/AuthService.cs)
 
+## Error handling
+
+Most Auth operations can throw `FirebaseAuthException`.  
+The exception contains:
+- `Reason`: a normalized enum for common Auth error cases
+- `ErrorCode`: the raw Firebase error code (useful for platform-specific handling)
+- `Email`: populated for account-collision cases when available
+
 ## Release notes
+- Version 4.0.1
+  - Improve `FirebaseAuthException` mapping and expose raw error details (`ErrorCode`, `Email`, and native error metadata) to support robust UI handling.
+- Version 4.0.0
+  - Upgrade baseline to **.NET 9+**.
+  - Remove MAUI-specific dependencies (Auth remains usable from non-MAUI mobile .NET projects).
+    - Android initialization now requires an `ActivityLocator` function (e.g. `() => Platform.CurrentActivity`).
+  - Raise minimum platform versions (iOS 15+, Android 23+).
+  - Raise minimum Firebase SDK versions (iOS 12.5+, Android BoM 33.0+).
+  - Remove built-in Auth provider implementations (Facebook/Google/Apple); providers must be implemented directly via native SDKs per platform.
 - Version 3.1.2
   - Fix NRE with Google Auth when cancelling sign in (#500)
 - Version 3.1.1

docs/ci-cd.md

@@ -0,0 +1,37 @@
+# CI/CD Guidance
+
+This repo targets multiple TFMs (`net9.0`, `net9.0-android`, `net9.0-ios`). CI can be kept
+lightweight by building `net9.0` only, and optionally adding Android/iOS builds on macOS.
+
+## Suggested CI stages
+1) **Restore + build (net9.0 only)**  
+   Fast validation on Linux/Windows runners.
+
+2) **Unit tests (net9.0)**  
+   Run lightweight unit tests for core mappings and helpers.
+
+3) **Android build (optional)**  
+   Requires Android SDK and `dotnet workload install android`.
+
+4) **iOS build (optional, macOS)**  
+   Requires Xcode + iOS workload.
+
+5) **Integration tests (manual/device)**  
+   Run on real devices using local Firebase configs.
+
+## Example GitHub Actions steps (snippet)
+```
+- uses: actions/setup-dotnet@v4
+  with:
+    dotnet-version: '9.x'
+- run: dotnet restore Plugin.Firebase.sln
+- run: dotnet build src/Auth/Auth.csproj -c Release -f net9.0
+- run: dotnet test tests/Plugin.Firebase.UnitTests/Plugin.Firebase.UnitTests.csproj -c Release --no-build
+```
+
+## Publishing
+Use `docs/packaging-github-packages.md` for packaging and push steps.
+
+## Repository workflows
+- CI (build + unit tests): `.github/workflows/ci.yml`
+- Publish to GitHub Packages (manual): `.github/workflows/publish-github-packages.yml`