Add Facebook Android interop wrapper and documentation

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.cs]
+indent_style = tab
+indent_size = 4
+
+[*.{yml,yaml,json,md,sh,gradle,kts,xml}]
+indent_style = space
+indent_size = 2

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Summary
+
+- What does this change do?
+
+## Checklist
+
+- [ ] No secrets committed
+- [ ] Built wrapper: `bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/build.sh`
+- [ ] Restored pinned AARs: `bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/restore-facebook-aars.sh`
+- [ ] Packed NuGet: `dotnet pack src/Kapusch.FacebookApisForAndroidComponents/Kapusch.FacebookApisForAndroidComponents.csproj -c Release -o artifacts/nuget`
+- [ ] Updated docs if behavior/integration changed

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: ci
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build_pack_android:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "10.0.x"
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: "microsoft"
+          java-version: "21"
+
+      - name: Setup Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: Install Android workload
+        run: |
+          dotnet workload install android
+
+      - name: Cache NuGet
+        uses: actions/cache@v4
+        with:
+          path: ~/.nuget/packages
+          key: ${{ runner.os }}-nuget-${{ hashFiles('global.json', '**/*.csproj') }}
+
+      - name: Build Android wrapper
+        run: |
+          bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/build.sh
+
+      - name: Restore pinned Facebook AARs
+        run: |
+          bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/restore-facebook-aars.sh
+
+      - name: Pack
+        run: |
+          dotnet pack src/Kapusch.FacebookApisForAndroidComponents/Kapusch.FacebookApisForAndroidComponents.csproj \
+            -c Release \
+            -o artifacts/nuget
+
+      - name: Build Android sample
+        run: |
+          dotnet build samples/Kapusch.Facebook.Android.Sample/Kapusch.Facebook.Android.Sample.csproj -c Debug
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: nuget
+          path: artifacts/nuget/*.nupkg

.github/workflows/publish.yml

@@ -0,0 +1,82 @@
+name: publish
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  pack_and_publish:
+    runs-on: ubuntu-latest
+    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/Kapusch.FacebookApisForAndroidComponents/Kapusch.FacebookApisForAndroidComponents.csproj"
+            BASE_VERSION=$(grep -oE '<Version>[^<]+' "$CSPROJ" | head -n 1 | sed 's/<Version>//' || 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: "10.0.x"
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: "microsoft"
+          java-version: "21"
+
+      - name: Setup Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: Install Android workload
+        run: |
+          dotnet workload install android
+
+      - name: Cache NuGet
+        uses: actions/cache@v4
+        with:
+          path: ~/.nuget/packages
+          key: ${{ runner.os }}-nuget-${{ hashFiles('global.json', '**/*.csproj') }}
+
+      - name: Build Android wrapper
+        run: |
+          bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/build.sh
+
+      - name: Restore pinned Facebook AARs
+        run: |
+          bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/restore-facebook-aars.sh
+
+      - name: Pack
+        run: |
+          dotnet pack src/Kapusch.FacebookApisForAndroidComponents/Kapusch.FacebookApisForAndroidComponents.csproj \
+            -c Release \
+            -o artifacts/nuget \
+            /p:PackageVersion="${{ steps.version.outputs.version }}"
+
+      - name: Push to GitHub Packages
+        env:
+          NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          dotnet nuget push artifacts/nuget/*.nupkg \
+            --api-key "$NUGET_AUTH_TOKEN" \
+            --source "https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json" \
+            --skip-duplicate

.gitignore

@@ -0,0 +1,36 @@
+# .NET
+bin/
+obj/
+*.user
+*.suo
+*.userosscache
+*.sln.docstates
+
+# NuGet
+*.nupkg
+*.snupkg
+artifacts/
+
+# macOS
+.DS_Store
+
+# Gradle / Android
+.gradle/
+**/.gradle/
+local.properties
+**/local.properties
+**/build/
+
+# Local caches used by restore
+.kapusch/
+
+# Native build output (repo-only)
+src/**/Native/Android/build/
+
+# Sample local config
+samples/**/google-services.json
+samples/**/secrets.*
+
+# Sample generated files
+samples/**/AndroidManifest.xml
+samples/**/strings.xml

AGENTS.md

@@ -0,0 +1,22 @@
+# Kapusch.FacebookApisForAndroidComponents — AI Working Agreement
+
+## Goals
+- Produce a reproducible Android NuGet package for Facebook Login interop.
+- Do not commit secrets.
+
+## Packaging constraints
+- Public OSS repo: keep docs/sample generic and not app-specific.
+- The NuGet ships the required `.aar` artifacts and injects them into consuming apps via `buildTransitive` `AndroidAarLibrary`.
+- Consuming apps must not download native deps at build time.
+- This repo may download dependencies during CI/build, but consuming apps must not.
+
+## Repo layout
+- `src/Kapusch.FacebookApisForAndroidComponents/` — NuGet project (managed API + buildTransitive MSBuild)
+- `src/Kapusch.FacebookApisForAndroidComponents/Native/Android/` — Gradle wrapper library + scripts (repo-only)
+- `DependencyLocks/` — pinned third-party artifacts (URLs + SHA256)
+- `Docs/` — integration docs
+- `samples/` — optional sample template (no secrets committed)
+
+## Safety
+- Do not add new dependency ingestion paths without documenting them in `README.md`.
+- Do not commit real app ids/secrets.

CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in this project and our community a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+- Being respectful and considerate in language and actions
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior include:
+- Harassment, discrimination, or hateful conduct
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Publishing others’ private information without explicit permission
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing standards.
+
+To report a Code of Conduct issue, contact the project maintainers.
+
+## Attribution
+
+This document is based on the Contributor Covenant.

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for contributing!
+
+## Prerequisites
+
+- JDK 21
+- Android SDK installed (set `ANDROID_SDK_ROOT` or `ANDROID_HOME`)
+- .NET SDK 10 (this repo pins `10.0.100` via `global.json`)
+
+## Local build
+
+If you are working without the NuGet (ProjectReference), see `Docs/SourceMode.md`.
+
+Build the Android wrapper AAR:
+
+- `bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/build.sh`
+
+Restore pinned Facebook AARs:
+
+- `bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/restore-facebook-aars.sh`
+
+Pack the NuGet:
+
+- `dotnet pack src/Kapusch.FacebookApisForAndroidComponents/Kapusch.FacebookApisForAndroidComponents.csproj -c Release -o artifacts/nuget`
+
+## Formatting
+
+- C#: follow `.editorconfig` (tabs, LF).
+- Java/Kotlin/Gradle: keep changes minimal and consistent with existing style.
+
+## Pull requests
+
+- Keep PRs focused and well-scoped.
+- Do not commit secrets.
+- If you update the Facebook SDK version, update both:
+  - `src/Kapusch.FacebookApisForAndroidComponents/Native/Android/facebookinterop/build.gradle.kts`
+  - `DependencyLocks/Android/lockstate.txt` (URLs + SHA256)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the repository license (MIT).

DependencyLocks/Android/lockstate.txt

@@ -0,0 +1,7 @@
+# Pinned Android artifacts for deterministic restore.
+# Format: <url> <sha256> <filename>
+
+https://repo1.maven.org/maven2/com/facebook/android/facebook-login/18.1.3/facebook-login-18.1.3.aar 30a0bb79b74244228c63101c26353ad61a973e156ca55b712b59fe56fc952100 facebook-login-18.1.3.aar
+https://repo1.maven.org/maven2/com/facebook/android/facebook-core/18.1.3/facebook-core-18.1.3.aar ef480916149e078f955195981130b05746ca33b41618911e7093aa32c03d601b facebook-core-18.1.3.aar
+https://repo1.maven.org/maven2/com/facebook/android/facebook-common/18.1.3/facebook-common-18.1.3.aar 62adfb1cd05184065d69033a9f917709b392004f87a8aa1cc1c4f0e9fb5ca781 facebook-common-18.1.3.aar
+https://repo1.maven.org/maven2/com/facebook/android/facebook-bolts/18.1.3/facebook-bolts-18.1.3.aar 05c6bae0130487e63add05854a3bbd21465c06a295a2104b3948d8759536b699 facebook-bolts-18.1.3.aar

Docs/Integration.md

@@ -0,0 +1,28 @@
+# Integration (Android)
+
+This package injects a small Android Activity (provided by an embedded AAR) that runs the Facebook Login flow and returns its result via `Intent` extras.
+
+## Required AndroidManifest entries
+
+You must include the required Meta/Facebook Android SDK entries in your app manifest (example only; use resources, do not hardcode secrets):
+
+- `com.facebook.sdk.ApplicationId`
+- `com.facebook.sdk.ClientToken`
+
+You also need to declare `com.facebook.FacebookActivity` and `com.facebook.CustomTabActivity` as per Facebook SDK documentation.
+
+## Launching the flow
+
+From your app, start the interop Activity:
+- `AndroidFacebookInterop.LoginActivityClassName`
+
+Then parse the `Intent` extras:
+- `AndroidFacebookInterop.ExtraStatus`
+- `AndroidFacebookInterop.ExtraAccessToken`
+- `AndroidFacebookInterop.ExtraUserId`
+- `AndroidFacebookInterop.ExtraErrorCode`
+- `AndroidFacebookInterop.ExtraErrorMessage`
+
+## Sign-out
+
+Call `AndroidFacebookInterop.SendSignOutBroadcast(context)`.

Docs/SourceMode.md

@@ -0,0 +1,13 @@
+# Source mode
+
+For local development, you can reference the project directly and inject the native AARs from the repo build output.
+
+## Steps
+
+1. Build native assets:
+   - `bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/build.sh`
+   - `bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/restore-facebook-aars.sh`
+2. Reference `src/Kapusch.FacebookApisForAndroidComponents/Kapusch.FacebookApisForAndroidComponents.csproj` from your app.
+3. Import the build targets:
+   - `src/Kapusch.FacebookApisForAndroidComponents/buildTransitive/Kapusch.Facebook.Android.targets`
+4. Set `UseKapuschFacebookAndroidInteropFromSource=true` in your app project.