@clix-so/clix-agent-skills 0.1.1

package/skills/integration/references/error-handling.md

@@ -0,0 +1,265 @@
+# Error Handling & Troubleshooting
+
+Common errors and solutions when integrating Clix SDK.
+
+## Initialization Errors
+
+### Error: "Project ID is required"
+
+**Symptoms:**
+
+- SDK fails to initialize
+- Error message indicates missing project ID
+
+**Solutions:**
+
+1. Verify `.env` file exists and contains `CLIX_PROJECT_ID`
+2. Check environment variable name matches exactly (case-sensitive)
+3. Ensure environment variables are loaded before initialization
+4. For frameworks with prefixes, use correct prefix (e.g., `NEXT_PUBLIC_`,
+   `VITE_`)
+
+**Prevention:**
+
+- Always check for environment variables before initialization
+- Provide default empty string if optional
+- Log warning if project ID is missing
+
+### Error: "Invalid API key"
+
+**Symptoms:**
+
+- SDK initializes but API calls fail
+- 401 Unauthorized errors
+
+**Solutions:**
+
+1. Verify API key is correct in environment variables
+2. Check for extra spaces or newlines in `.env` file
+3. Ensure API key hasn't been rotated/revoked
+4. Verify API key has correct permissions
+
+**Prevention:**
+
+- Never commit API keys to version control
+- Use environment variables, never hardcode
+- Validate API key format if possible
+
+### Error: "SDK already initialized"
+
+**Symptoms:**
+
+- Warning or error about double initialization
+- May cause unexpected behavior
+
+**Solutions:**
+
+1. Ensure initialization happens only once
+2. Check for multiple initialization calls
+3. Use singleton pattern or guard clause
+
+**Prevention:**
+
+```typescript
+let initialized = false;
+
+if (!initialized) {
+  Clix.initialize(config);
+  initialized = true;
+}
+```
+
+## Environment Variable Issues
+
+### Variables Not Loading
+
+**Symptoms:**
+
+- `process.env.CLIX_PROJECT_ID` is `undefined`
+- Values are empty strings
+
+**Solutions:**
+
+**Node.js:**
+
+- Ensure `dotenv` is installed and configured
+- Call `require('dotenv').config()` before using variables
+- Check `.env` file is in project root
+
+**React/Vite:**
+
+- Use correct prefix: `VITE_CLIX_PROJECT_ID`
+- Restart dev server after adding variables
+- Check `.env` file is in project root
+
+**Next.js:**
+
+- Use `NEXT_PUBLIC_` prefix for client-side variables
+- Restart dev server after changes
+- Check `.env.local` for local development
+
+**React Native:**
+
+- Use `react-native-config` package
+- Rebuild native apps after adding variables
+- Check `.env` file is in project root
+
+### Wrong Variable Names
+
+**Symptoms:**
+
+- Variables exist but have different names
+- SDK can't find credentials
+
+**Solutions:**
+
+1. Check existing `.env` files for variable names
+2. Use consistent naming: `CLIX_PROJECT_ID` and `CLIX_PUBLIC_API_KEY`
+3. Update all references to use correct names
+
+## Platform-Specific Errors
+
+### iOS: "No such module 'Clix'"
+
+**Solutions:**
+
+1. Run `pod install` in project directory
+2. Clean build folder (Cmd+Shift+K)
+3. Verify Podfile includes Clix dependency
+4. Check Xcode project settings for Swift Package Manager
+
+### Android: "Unresolved reference: Clix"
+
+**Solutions:**
+
+1. Sync Gradle files
+2. Verify `build.gradle` includes Clix dependency
+3. Check package name matches: `so.clix.core.Clix`
+4. Rebuild project
+
+### React Native: "Cannot find module '@clix-so/react-native-sdk'"
+
+**Solutions:**
+
+1. Run `npm install` or `yarn install`
+2. Run `pod install` in `ios/` directory
+3. Rebuild native apps
+4. Check `package.json` includes dependency
+
+### Node.js: "Cannot find module '@clix/node-sdk'"
+
+**Solutions:**
+
+1. Run `npm install` or `yarn install`
+2. Check `package.json` includes dependency
+3. Verify node_modules directory exists
+4. Clear npm cache and reinstall
+
+### Web: "Clix is not defined"
+
+**Solutions:**
+
+1. Ensure SDK is imported before use
+2. Check bundle includes SDK code
+3. Verify initialization happens before SDK usage
+4. Check for build/bundling errors
+
+## MCP Server Errors
+
+### Error: "MCP server not found"
+
+**Solutions:**
+
+1. Verify MCP server is installed: `npx -y @clix-so/clix-mcp-server@latest`
+2. Check MCP config file syntax is valid JSON
+3. Verify config file is in correct location for agent
+4. Restart AI agent after configuration changes
+
+### Error: "MCP tool calls failing"
+
+**Solutions:**
+
+1. Check MCP server can be invoked manually
+2. Verify credentials are accessible to MCP server
+3. Check network connectivity
+4. Review MCP server logs for errors
+
+## Integration Verification
+
+### Verify SDK Initialization
+
+**Checklist:**
+
+1. ✅ SDK initialized before any usage
+2. ✅ Initialization completed without errors
+3. ✅ Environment variables are accessible
+4. ✅ No console errors or warnings during initialization
+5. ✅ SDK is properly imported/required
+
+**Verification Steps:**
+
+1. Run `bash scripts/validate-sdk.sh` to check installation
+2. Check console logs for initialization messages
+3. Verify SDK import/require statements are correct
+4. Confirm environment variables are loaded correctly
+
+## Best Practices for Error Handling
+
+### Always Handle Errors Gracefully
+
+```typescript
+try {
+  Clix.initialize(config);
+} catch (error) {
+  console.error("Clix initialization failed:", error);
+  // Don't crash the app - continue execution
+}
+```
+
+### Validate Configuration
+
+```typescript
+if (!config.projectId) {
+  console.warn("Clix: Project ID is missing");
+  return;
+}
+
+Clix.initialize(config);
+```
+
+### Log Errors for Debugging
+
+```typescript
+try {
+  Clix.trackEvent("event", properties);
+} catch (error) {
+  console.error("Clix tracking failed:", error);
+  // Optionally send to error tracking service
+}
+```
+
+### Provide Fallbacks
+
+```typescript
+const projectId =
+  process.env.CLIX_PROJECT_ID || process.env.REACT_APP_CLIX_PROJECT_ID || "";
+
+if (!projectId) {
+  console.warn("Clix: No project ID found, analytics disabled");
+  return;
+}
+```
+
+## Getting Help
+
+If you encounter errors not covered here:
+
+1. Check SDK documentation for your platform
+2. Review GitHub issues for similar problems
+3. Enable debug mode and check logs
+4. Verify SDK version is up to date
+5. Contact Clix support with:
+   - Error message
+   - Platform and version
+   - SDK version
+   - Steps to reproduce

package/skills/integration/references/framework-patterns.md

@@ -0,0 +1,201 @@
+# Framework-Specific Integration Patterns (Mobile)
+
+This document provides detailed patterns for integrating the Clix SDK into
+**mobile** frameworks and platforms:
+
+- iOS (Swift)
+- Android (Kotlin)
+- Flutter
+- React Native
+
+Examples below are derived strictly from the official SDK source code (via Clix
+MCP `search_sdk`), with credentials shown as placeholders (`YOUR_PROJECT_ID`,
+`YOUR_PUBLIC_API_KEY`).
+
+---
+
+---
+
+> **Note: Fallback Source** This document serves as a **fallback** when the Clix
+> MCP Server is unavailable. Agents should **prioritize** using `search_sdk` to
+> fetch the latest live patterns from the official SDK repositories before
+> relying on these static examples.
+
+---
+
+## iOS (Swift)
+
+### AppDelegate Pattern (UIKit)
+
+**Reference**: `ClixConfig.swift` (from `clix-ios-sdk`)
+
+```swift
+import UIKit
+import Clix
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        // Initialize ClixConfig with params
+        let config = ClixConfig(
+            projectId: ProcessInfo.processInfo.environment["CLIX_PROJECT_ID"] ?? "",
+            apiKey: ProcessInfo.processInfo.environment["CLIX_PUBLIC_API_KEY"] ?? "",
+            logLevel: .info // Optional: .debug, .info, .error
+        )
+
+        // Pass config to initialize
+        try? Clix.initialize(config: config)
+
+        return true
+    }
+}
+```
+
+### SwiftUI Pattern
+
+```swift
+import SwiftUI
+import Clix
+
+@main
+struct MyApp: App {
+    init() {
+        let config = ClixConfig(
+            projectId: ProcessInfo.processInfo.environment["CLIX_PROJECT_ID"] ?? "",
+            apiKey: ProcessInfo.processInfo.environment["CLIX_PUBLIC_API_KEY"] ?? ""
+        )
+        try? Clix.initialize(config: config)
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+```
+
+## Android (Kotlin)
+
+**Reference**: `ClixConfig.kt` (from `clix-android-sdk`)
+
+### Application Class Pattern
+
+```kotlin
+import android.app.Application
+import so.clix.core.Clix
+import so.clix.core.ClixConfig
+import so.clix.utils.logging.ClixLogLevel
+
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+
+        val projectId = BuildConfig.CLIX_PROJECT_ID ?: ""
+        val apiKey = BuildConfig.CLIX_PUBLIC_API_KEY ?: ""
+
+
+        val config = ClixConfig(
+            projectId = projectId,
+            apiKey = apiKey,
+            logLevel = ClixLogLevel.INFO
+        )
+
+        Clix.initialize(this, config)
+    }
+}
+```
+
+## React Native
+
+**Reference**: `index.js` (from `clix-react-native-sdk`)
+
+### Root Component Pattern
+
+```typescript
+// App.tsx
+import React, { useEffect } from 'react';
+import { Clix } from '@clix-so/react-native-sdk'; // Note user scope @clix-so
+import Config from 'react-native-config';
+
+export default function App() {
+  useEffect(() => {
+    // Initialize takes a config object
+    Clix.initialize({
+      projectId: Config.CLIX_PROJECT_ID || '',
+      apiKey: Config.CLIX_PUBLIC_API_KEY,
+      // logLevel: 'info' // Optional
+    });
+  }, []);
+
+  return (
+    // Your app components
+  );
+}
+```
+
+## Flutter
+
+**Reference**: `clix_config.dart` (from `clix-flutter-sdk`)
+
+### Main Function Pattern
+
+```dart
+import 'package:clix_flutter/clix_flutter.dart';
+import 'package:flutter/material.dart';
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  const projectId = String.fromEnvironment('CLIX_PROJECT_ID');
+  const apiKey = String.fromEnvironment('CLIX_PUBLIC_API_KEY');
+
+  // Initialize with ClixConfig object
+  await Clix.initialize(
+    ClixConfig(
+      projectId: projectId,
+      apiKey: apiKey,
+      logLevel: ClixLogLevel.info,
+    ),
+  );
+
+  runApp(const MyApp());
+}
+```
+
+## Common Patterns
+
+### Error Handling
+
+Always wrap initialization in try-catch (Swift) or catch errors (Promise-based
+platforms):
+
+```typescript
+// React Native / Flutter
+try {
+  await Clix.initialize(config);
+} catch (error) {
+  console.error("Clix initialization failed:", error);
+}
+```
+
+### Conditional Initialization
+
+Only initialize in production or specific environments:
+
+```typescript
+if (!__DEV__) {
+  Clix.initialize(config);
+}
+```
+
+### Credentials
+
+- Use placeholders like `YOUR_PROJECT_ID` and `YOUR_PUBLIC_API_KEY` in examples
+- In real apps, load credentials from safe configuration (config files, build
+  config, secret managers)
+- Avoid hardcoding real credentials directly in source code or examples checked
+  into version control