@shaykec/app-agent 1.0.5 → 1.0.7

package/templates/shared/android/SecretsConfig/SecretsConfig.kt

@@ -0,0 +1,113 @@
+package com.appship.shared.secrets
+
+import android.util.Log
+
+/**
+ * Reads API keys and secrets from BuildConfig fields (injected via secrets.properties at build time).
+ * A warning is logged if a key is missing or has a placeholder value.
+ *
+ * Usage:
+ *   val clientId = SecretsConfig.wixClientId
+ *
+ * Setup:
+ *   1. Copy secrets.properties.template -> secrets.properties
+ *   2. Fill in your API keys
+ *   3. Ensure secrets.properties is in .gitignore
+ */
+object SecretsConfig {
+
+    private const val TAG = "SecretsConfig"
+
+    // MARK: - Wix
+
+    /** Wix OAuth app client ID (for WixMemberBackend) */
+    val wixClientId: String get() = getField("WIX_CLIENT_ID")
+
+    /** Wix site ID */
+    val wixSiteId: String get() = getField("WIX_SITE_ID")
+
+    /** Wix API key (for WixOwnerBackend — site owner/admin access) */
+    val wixApiKey: String get() = getField("WIX_API_KEY")
+
+    // Note: WIX_REDIRECT_URL is auto-derived from the app's package name.
+    // See WixAuthManager for details.
+
+    // MARK: - Firebase
+
+    // Firebase uses google-services.json — no keys needed here.
+    // The Firebase SDK reads its configuration automatically.
+
+    // MARK: - Supabase
+
+    /** Supabase project URL (e.g., https://yourproject.supabase.co) */
+    val supabaseUrl: String get() = getField("SUPABASE_URL")
+
+    /** Supabase anonymous/public key (client-safe, protected by RLS) */
+    val supabaseAnonKey: String get() = getField("SUPABASE_ANON_KEY")
+
+    // MARK: - Convenience Checks
+
+    /**
+     * Returns true if Wix member credentials are configured (clientId required, siteId optional).
+     * Site ID is no longer required here — it can be selected at runtime via WixSiteSelector.
+     */
+    val isWixMemberConfigured: Boolean
+        get() = isConfigured("WIX_CLIENT_ID")
+
+    /**
+     * Returns true if Wix owner credentials are configured (apiKey required, siteId optional).
+     * Site ID is no longer required here — it can be selected at runtime via WixSiteSelector.
+     */
+    val isWixOwnerConfigured: Boolean
+        get() = isConfigured("WIX_API_KEY")
+
+    /** Returns true if Supabase credentials are configured (url + anonKey). */
+    val isSupabaseConfigured: Boolean
+        get() = isConfigured("SUPABASE_URL") && isConfigured("SUPABASE_ANON_KEY")
+
+    // MARK: - Helpers
+
+    /**
+     * Reads a BuildConfig field by name using reflection.
+     * Returns empty string and logs a warning if the field is missing or has a placeholder value.
+     */
+    private fun getField(fieldName: String): String {
+        return try {
+            val buildConfigClass = Class.forName("${getBuildConfigPackage()}.BuildConfig")
+            val field = buildConfigClass.getField(fieldName)
+            val value = field.get(null) as? String ?: ""
+            if (value.isEmpty() || value.startsWith("YOUR_") || value.startsWith("your-")) {
+                Log.w(TAG, "'$fieldName' is not configured. See secrets.properties.template for setup instructions.")
+                ""
+            } else {
+                value
+            }
+        } catch (e: Exception) {
+            Log.w(TAG, "'$fieldName' is not configured. See secrets.properties.template for setup instructions.")
+            ""
+        }
+    }
+
+    /**
+     * Returns true if the given BuildConfig field has a non-empty, non-placeholder value.
+     */
+    fun isConfigured(fieldName: String): Boolean {
+        return try {
+            val buildConfigClass = Class.forName("${getBuildConfigPackage()}.BuildConfig")
+            val field = buildConfigClass.getField(fieldName)
+            val value = field.get(null) as? String ?: ""
+            value.isNotEmpty() && !value.startsWith("YOUR_") && !value.startsWith("your-")
+        } catch (e: Exception) {
+            false
+        }
+    }
+
+    /**
+     * Returns the app's package name for BuildConfig access.
+     * CUSTOMIZE: Replace with your actual package name if reflection doesn't work.
+     */
+    private fun getBuildConfigPackage(): String {
+        // This will be replaced by the agent with the actual app package name
+        return "com.appship.app" // CUSTOMIZE:PACKAGE_NAME
+    }
+}

package/templates/shared/android/SecretsConfig/build.gradle.snippet.kts

@@ -0,0 +1,36 @@
+// ── SecretsConfig: Add this to your app/build.gradle.kts ──
+// This snippet reads secrets.properties and injects values as BuildConfig fields.
+// Place it inside the android { defaultConfig { ... } } block.
+
+// --- Add at the top of build.gradle.kts ---
+import java.util.Properties
+
+// --- Add inside android { defaultConfig { } } ---
+val secretsFile = rootProject.file("secrets.properties")
+if (secretsFile.exists()) {
+    val secrets = Properties().apply { load(secretsFile.inputStream()) }
+
+    // Wix
+    buildConfigField("String", "WIX_CLIENT_ID", "\"${secrets.getProperty("WIX_CLIENT_ID", "")}\"")
+    buildConfigField("String", "WIX_SITE_ID", "\"${secrets.getProperty("WIX_SITE_ID", "")}\"")
+    buildConfigField("String", "WIX_API_KEY", "\"${secrets.getProperty("WIX_API_KEY", "")}\"")
+    // Note: WIX_REDIRECT_URL is auto-derived from the package name — no config needed
+
+    // Supabase
+    buildConfigField("String", "SUPABASE_URL", "\"${secrets.getProperty("SUPABASE_URL", "")}\"")
+    buildConfigField("String", "SUPABASE_ANON_KEY", "\"${secrets.getProperty("SUPABASE_ANON_KEY", "")}\"")
+} else {
+    // Provide empty defaults so the build doesn't fail without secrets.properties
+    buildConfigField("String", "WIX_CLIENT_ID", "\"\"")
+    buildConfigField("String", "WIX_SITE_ID", "\"\"")
+    buildConfigField("String", "WIX_API_KEY", "\"\"")
+    buildConfigField("String", "SUPABASE_URL", "\"\"")
+    buildConfigField("String", "SUPABASE_ANON_KEY", "\"\"")
+}
+
+// --- Also ensure buildFeatures { buildConfig = true } is set ---
+// android {
+//     buildFeatures {
+//         buildConfig = true
+//     }
+// }

package/templates/shared/android/SecretsConfig/secrets.properties.template

@@ -0,0 +1,31 @@
+# secrets.properties — API keys and secrets
+# ─────────────────────────────────────────────────────────────
+# SETUP:
+#   1. Copy this file:  cp secrets.properties.template secrets.properties
+#   2. Fill in your keys below
+#   3. secrets.properties is already in .gitignore — never commit it
+#
+# These values are injected as BuildConfig fields at build time.
+# Access them in code via SecretsConfig (e.g., SecretsConfig.wixClientId).
+# ─────────────────────────────────────────────────────────────
+
+# ── Wix (Member / Customer apps) ──
+# Get your Client ID from https://dev.wix.com > OAuth Apps
+# Site ID is optional — the app can use WixSiteSelector for runtime selection.
+# Redirect URL is auto-derived from the package name ({packageName}://oauth/callback).
+WIX_CLIENT_ID=YOUR_WIX_CLIENT_ID
+WIX_SITE_ID=YOUR_WIX_SITE_ID
+
+# ── Wix (Owner / Admin apps) ──
+# Get this from Wix Dashboard > Settings > API Keys
+WIX_API_KEY=YOUR_WIX_API_KEY
+
+# ── Supabase ──
+# Get these from https://supabase.com/dashboard > Project Settings > API
+SUPABASE_URL=YOUR_SUPABASE_URL
+SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
+
+# ── Firebase ──
+# Firebase does NOT use this file.
+# Instead, download google-services.json from Firebase Console
+# and place it in the app/ directory.

package/templates/shared/android/SupabaseBackend/INTEGRATION.md

@@ -0,0 +1,514 @@
+# SupabaseBackend Module — Integration Guide
+
+## Overview
+
+The SupabaseBackend module provides a comprehensive wrapper around the official Supabase Kotlin SDK (`supabase-kt`). It includes:
+
+- **Authentication** — Email/password, magic link (OTP), OAuth (Google, Apple, GitHub, Facebook)
+- **Database** — PostgREST query builder with type-safe models
+- **Storage** — File uploads, downloads, and public URL generation
+- **Realtime** — Postgres Changes subscriptions via Flow
+- **Configuration** — Centralized client initialization from SecretsConfig
+
+## Prerequisites
+
+### 1. Add Supabase Kotlin SDK
+
+Add the Supabase BOM and dependencies to `app/build.gradle.kts`:
+
+```kotlin
+dependencies {
+    // Supabase BOM (manages versions)
+    implementation(platform("io.github.jan-tennert.supabase:bom:2.0.0"))
+    
+    // Supabase modules
+    implementation("io.github.jan-tennert.supabase:postgrest-kt")
+    implementation("io.github.jan-tennert.supabase:gotrue-kt")
+    implementation("io.github.jan-tennert.supabase:realtime-kt")
+    implementation("io.github.jan-tennert.supabase:storage-kt")
+    
+    // Kotlinx Serialization (required for Supabase)
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
+}
+```
+
+### 2. Configure SecretsConfig
+
+Add Supabase credentials to `SecretsConfig.kt`:
+
+```kotlin
+// In SecretsConfig.kt
+object SecretsConfig {
+    val supabaseUrl: String
+        get() = getSecret("SUPABASE_URL")
+    
+    val supabaseAnonKey: String
+        get() = getSecret("SUPABASE_ANON_KEY")
+}
+```
+
+Add these keys to your `secrets.properties` file:
+
+```properties
+SUPABASE_URL=https://yourproject.supabase.co
+SUPABASE_ANON_KEY=your-anon-key-here
+```
+
+### 3. Initialize Supabase Client
+
+The `SupabaseConfigManager` automatically initializes the client using `SecretsConfig`. Access it via:
+
+```kotlin
+import com.appship.shared.supabase.SupabaseConfigManager
+
+val supabase = SupabaseConfigManager.client
+```
+
+## Deep Link Setup
+
+For magic link and OAuth callbacks, configure deep links in your Android app:
+
+### 1. Add Intent Filter to AndroidManifest.xml
+
+Add to your main activity or a dedicated deep link activity:
+
+```xml
+<activity
+    android:name=".MainActivity"
+    android:exported="true">
+    <!-- Existing intent filters -->
+    
+    <!-- Supabase OAuth callback -->
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data
+            android:scheme="com.yourapp"
+            android:host="auth" />
+    </intent-filter>
+    
+    <!-- Magic link callback -->
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data
+            android:scheme="https"
+            android:host="yourproject.supabase.co"
+            android:pathPrefix="/auth/v1/verify" />
+    </intent-filter>
+</activity>
+```
+
+### 2. Handle Deep Links in Activity
+
+```kotlin
+import android.content.Intent
+import android.net.Uri
+import com.appship.shared.supabase.SupabaseConfigManager
+import kotlinx.coroutines.launch
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        
+        // Handle deep link on launch
+        handleDeepLink(intent)
+    }
+    
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        handleDeepLink(intent)
+    }
+    
+    private fun handleDeepLink(intent: Intent) {
+        val uri: Uri? = intent.data
+        if (uri != null) {
+            lifecycleScope.launch {
+                try {
+                    // Handle Supabase OAuth callback
+                    SupabaseConfigManager.client.auth.sessionFromDeepLink(uri)
+                } catch (e: Exception) {
+                    Log.e("MainActivity", "Deep link error", e)
+                }
+            }
+        }
+    }
+}
+```
+
+### 3. Configure Supabase Redirect URLs
+
+In Supabase Dashboard → **Authentication → URL Configuration**:
+
+- Add redirect URL: `com.yourapp://auth/callback`
+- Add site URL: `com.yourapp://`
+
+## AppConfig Additions
+
+Add to `AppConfig`:
+
+```kotlin
+object AppConfig {
+    object Features {
+        const val enableSupabaseBackend = true
+        const val enableSupabaseAuth = true
+        const val enableSupabaseOAuth = true
+        const val enableSupabaseMagicLink = true
+    }
+}
+```
+
+## Navigation Wiring
+
+### Auth Flow
+
+Add authentication gate to Profile screen or as onboarding:
+
+```kotlin
+@Composable
+fun ProfileScreen() {
+    val authManager = remember {
+        SupabaseAuthManager(SupabaseConfigManager.client)
+    }
+    val authState by authManager.authState.collectAsState()
+    
+    if (authState == SupabaseAuthManager.AuthState.LOGGED_IN) {
+        SupabaseProfileScreen(
+            authManager = authManager,
+            onSignOut = {
+                // Navigate to login
+            }
+        )
+    } else {
+        SupabaseLoginScreen(
+            authManager = authManager,
+            onSuccess = {
+                // Navigate to main app content
+            },
+            onSignUp = {
+                // Navigate to sign up
+            }
+        )
+    }
+}
+```
+
+### Login Screen
+
+```kotlin
+SupabaseLoginScreen(
+    authManager = authManager,
+    onSuccess = {
+        // Handle successful login
+    },
+    onSignUp = {
+        navController.navigate("signup")
+    }
+)
+```
+
+### Sign Up Screen
+
+```kotlin
+SupabaseSignUpScreen(
+    authManager = authManager,
+    onSuccess = {
+        // Handle successful sign up
+    },
+    onSignIn = {
+        navController.popBackStack()
+    }
+)
+```
+
+### Magic Link Sent Screen
+
+```kotlin
+SupabaseMagicLinkSentScreen(
+    authManager = authManager,
+    email = email,
+    onBack = {
+        navController.popBackStack()
+    }
+)
+```
+
+### Profile Screen
+
+```kotlin
+SupabaseProfileScreen(
+    authManager = authManager,
+    onSignOut = {
+        // Navigate to login
+    },
+    onDeleteAccount = {
+        // Handle account deletion
+    },
+    onNavigateToLogin = {
+        navController.navigate("login")
+    }
+)
+```
+
+## Service Usage
+
+### SupabaseAuthManager
+
+```kotlin
+val authManager = SupabaseAuthManager(SupabaseConfigManager.client)
+
+// Sign in with email
+lifecycleScope.launch {
+    try {
+        authManager.signInWithEmail("user@example.com", "password123")
+    } catch (e: Exception) {
+        // Handle error
+    }
+}
+
+// Sign up
+lifecycleScope.launch {
+    try {
+        authManager.signUp("user@example.com", "password123")
+    } catch (e: Exception) {
+        // Handle error
+    }
+}
+
+// Sign in with magic link
+lifecycleScope.launch {
+    try {
+        authManager.signInWithMagicLink("user@example.com")
+        // Navigate to SupabaseMagicLinkSentScreen
+    } catch (e: Exception) {
+        // Handle error
+    }
+}
+
+// Sign in with OAuth
+lifecycleScope.launch {
+    try {
+        authManager.signInWithOAuth(SupabaseAuthManager.OAuthProvider.GOOGLE)
+        // OAuth flow continues in browser/deep link
+    } catch (e: Exception) {
+        // Handle error
+    }
+}
+
+// Send password reset
+lifecycleScope.launch {
+    try {
+        authManager.sendPasswordReset("user@example.com")
+    } catch (e: Exception) {
+        // Handle error
+    }
+}
+
+// Sign out
+lifecycleScope.launch {
+    try {
+        authManager.signOut()
+    } catch (e: Exception) {
+        // Handle error
+    }
+}
+
+// Delete account
+lifecycleScope.launch {
+    try {
+        authManager.deleteAccount()
+    } catch (e: Exception) {
+        // Handle error
+    }
+}
+
+// Observe auth state
+authManager.authState.collect { state ->
+    when (state) {
+        SupabaseAuthManager.AuthState.LOGGED_OUT -> {
+            // Show login screen
+        }
+        SupabaseAuthManager.AuthState.AUTHENTICATING -> {
+            // Show loading
+        }
+        SupabaseAuthManager.AuthState.LOGGED_IN -> {
+            // Show app content
+        }
+        SupabaseAuthManager.AuthState.ERROR -> {
+            // Show error
+        }
+    }
+}
+
+// Get current user
+val currentUser = authManager.currentUser.value
+```
+
+### SupabaseDatabaseManager
+
+```kotlin
+val database = SupabaseDatabaseManager(SupabaseConfigManager.client)
+
+// Select all items
+lifecycleScope.launch {
+    val items: List<MyModel> = database
+        .from("items")
+        .select()
+}
+
+// Select with filters
+lifecycleScope.launch {
+    val filtered: List<MyModel> = database
+        .from("items")
+        .eq("category", "books")
+        .order("created_at", ascending = false)
+        .limit(10)
+        .select()
+}
+
+// Insert
+lifecycleScope.launch {
+    database
+        .from("items")
+        .insert(newItem)
+}
+
+// Update
+lifecycleScope.launch {
+    database
+        .from("items")
+        .eq("id", itemId)
+        .update(mapOf("title" to "New Title"))
+}
+
+// Delete
+lifecycleScope.launch {
+    database
+        .from("items")
+        .eq("id", itemId)
+        .delete()
+}
+```
+
+### SupabaseStorageManager
+
+```kotlin
+val storage = SupabaseStorageManager(SupabaseConfigManager.client)
+
+// Upload file
+lifecycleScope.launch {
+    val url = storage.upload(
+        bucket = "avatars",
+        path = "user-123.jpg",
+        data = imageData
+    )
+}
+
+// Download file
+lifecycleScope.launch {
+    val data = storage.download(
+        bucket = "avatars",
+        path = "user-123.jpg"
+    )
+}
+
+// Get public URL
+val publicUrl = storage.getPublicUrl(
+    bucket = "avatars",
+    path = "user-123.jpg"
+)
+
+// Delete file
+lifecycleScope.launch {
+    storage.delete(
+        bucket = "avatars",
+        path = "user-123.jpg"
+    )
+}
+```
+
+### SupabaseRealtimeManager
+
+```kotlin
+val realtime = SupabaseRealtimeManager(SupabaseConfigManager.client)
+
+// Subscribe to changes
+lifecycleScope.launch {
+    realtime.subscribe("items")
+        .collect { change ->
+            when (change.eventType) {
+                "INSERT" -> {
+                    // Handle insert
+                }
+                "UPDATE" -> {
+                    // Handle update
+                }
+                "DELETE" -> {
+                    // Handle delete
+                }
+            }
+        }
+}
+```
+
+## String Resources
+
+All strings are in `strings.xml`. Ensure the module's `strings.xml` is merged into your app's resources by including it in your `res/values/` directory or via a library module.
+
+## Test IDs
+
+| Test ID | Element |
+|---------|---------|
+| `supabase_login_title` | Login screen title |
+| `supabase_login_email_field` | Email text field |
+| `supabase_login_password_field` | Password text field |
+| `supabase_login_magic_link_toggle` | Magic link toggle |
+| `supabase_login_sign_in_button` | Sign in button |
+| `supabase_login_forgot_password_button` | Forgot password button |
+| `supabase_login_google_button` | Google OAuth button |
+| `supabase_login_apple_button` | Apple OAuth button |
+| `supabase_login_github_button` | GitHub OAuth button |
+| `supabase_signup_title` | Sign up screen title |
+| `supabase_signup_email_field` | Email text field |
+| `supabase_signup_password_field` | Password text field |
+| `supabase_signup_confirm_password_field` | Confirm password field |
+| `supabase_signup_create_account_button` | Create account button |
+| `supabase_forgot_password_title` | Forgot password title |
+| `supabase_forgot_password_email_field` | Email text field |
+| `supabase_forgot_password_send_button` | Send reset link button |
+| `supabase_magic_link_icon` | Magic link sent icon |
+| `supabase_magic_link_title` | Magic link sent title |
+| `supabase_magic_link_message` | Magic link sent message |
+| `supabase_magic_link_instructions` | Magic link instructions |
+| `supabase_magic_link_open_email_button` | Open email button |
+| `supabase_magic_link_resend_button` | Resend magic link button |
+| `supabase_magic_link_back_button` | Back button |
+| `supabase_profile_avatar` | Profile avatar |
+| `supabase_profile_email` | Profile email |
+| `supabase_profile_provider_badge` | Provider badge |
+| `supabase_profile_sign_out_button` | Sign out button |
+| `supabase_profile_delete_account_button` | Delete account button |
+| `supabase_profile_delete_confirm_button` | Delete confirmation button |
+| `supabase_profile_delete_cancel_button` | Delete cancel button |
+| `supabase_profile_lock_icon` | Login prompt lock icon |
+| `supabase_profile_login_prompt_title` | Login prompt title |
+| `supabase_profile_login_prompt_message` | Login prompt message |
+| `supabase_profile_navigate_to_login_button` | Navigate to login button |
+
+## Module Dependencies
+
+- **SecretsConfig** — Required for Supabase URL and anon key
+- **ErrorHandling** (optional) — For displaying auth errors
+- **NetworkBanner** (optional) — For connectivity awareness
+
+## Usage Notes
+
+- **Row-Level Security:** Always enable RLS on tables and create policies for user isolation
+- **Magic Links:** Magic link authentication sends an email. Handle the deep link in your app
+- **OAuth Setup:** Configure OAuth providers in Supabase Dashboard → Authentication → Providers
+- **Storage Buckets:** Create storage buckets in Supabase Dashboard → Storage
+- **Realtime:** Realtime subscriptions require WebSocket connection. Handle disconnections gracefully
+- **Session Management:** The auth manager automatically checks for existing sessions on initialization
+- **Deep Links:** Ensure your app's package name matches the deep link scheme (e.g., `com.yourapp`)