# SnappySnag Full Reference & Implementation Guide for AI Agents

> This document contains comprehensive, end-to-end integration instructions, complete runnable code snippets, and API specifications for SnappySnag Flutter SDK (`package:snappy_snag`).

---

## 1. Package Installation

Add the official Flutter package to your app:

```bash
flutter pub add snappy_snag
```

Or add directly to `pubspec.yaml`:

```yaml
dependencies:
  flutter:
    sdk: flutter
  snappy_snag: ^0.0.2
```

---

## 2. Complete, Copy-Ready `main.dart` Example

This is a complete, production-ready `main.dart` demonstrating proper SDK initialization, dynamic user identity, and UI wrapping.

```dart
import 'package:flutter/material.dart';
import 'package:flutter/foundation.dart';
import 'package:snappy_snag/snappy_snag.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Initialize the SDK
  SnappySnag().initialize(
    // Your project API Key obtained from https://snappysnag.com/dashboard
    apiKey: 'snag_live_your_api_key_here',

    // Optional: Identify logged-in user or QA tester (can also be updated later via SnappySnag().setUser())
    user: const SnappySnagUser(
      email: 'tester@example.com',
    ),

    // Optional: Lock API requests to your registered bundle ID (e.g. com.example.myapp)
    // packageName: 'com.example.myapp',

    // Display floating overlay capture button (defaults to false for clean UI)
    showTriggerButton: true,

    // Flexible enablement:
    // Option A: Active in debug and internal test builds:
    enabled: const bool.fromEnvironment('ENABLE_SNAPPY_SNAG', defaultValue: false) || kDebugMode,
    // Option B: Always active for in-app user feedback:
    // enabled: true,
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'SnappySnag Demo App',
      // 2. Set default navigator key for dialogs and navigation context
      navigatorKey: SnappySnag.defaultNavigatorKey,

      // 3. Wrap your screen with SnappySnagOverlay in builder
      builder: (context, child) => SnappySnagOverlay(
        child: child ?? const SizedBox.shrink(),
      ),

      home: const HomeScreen(),
    );
  }
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('SnappySnag Home')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('Shake device or tap floating button to report feedback!'),
            const SizedBox(height: 20),
            ElevatedButton.icon(
              icon: const Icon(Icons.feedback_outlined),
              label: const Text('Report Feedback / Bug'),
              onPressed: () {
                // Programmatically trigger feedback flow from in-app settings or help menu
                SnappySnag.startFeedbackMode(context: context);
              },
            ),
          ],
        ),
      ),
    );
  }
}
```

---

## 3. Configuration Parameters (`SnappySnag().initialize`)

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `apiKey` | `String` | **Required** | Project API key starting with `snag_live_...`. |
| `mode` | `SnappySnagMode`| `SnappySnagMode.user` | `user` (clean feedback flow for end-users) or `dev` (shows duplicate warnings & internal tickets for QA). |
| `packageName` | `String?` | `null` | Optional bundle identifier locking. Prevents unauthorized API requests if key is exposed. |
| `user` | `SnappySnagUser?` | `null` | Initial user identifier (`email`, `id`, `name`). Matches team members in dashboard. |
| `showTriggerButton`| `bool` | `false` | When true, renders floating capture button on screen. |
| `enabled` | `bool` | `true` | Master switch. When false, suppresses overlay rendering and sensor listeners entirely. |
| `enableWidgetTree` | `bool` | `true` | Traverses Flutter UI tree (up to 10 levels) for Gemini AI context. Auto-redacts passwords and input fields. |
| `enableLogging` | `bool` | `false` | Suppresses verbose console logs. Critical errors are always output. |

---

## 4. Dynamic User State & Authentication

When users log in or log out after app startup:

```dart
// On login:
SnappySnag().setUser(SnappySnagUser(
  email: currentUser.email,
  id: currentUser.id,
  name: currentUser.displayName,
));

// On logout:
SnappySnag().clearUser();
```

---

## 5. UI Control & Manual Triggering

- **Hide floating button on specific sensitive screens** (e.g. Camera, Payment, Video):
  ```dart
  SnappySnagHideButton(
    child: CameraScreenView(),
  )
  ```
- **Programmatic visibility control**:
  ```dart
  SnappySnag().showTriggerButton();
  SnappySnag().hideTriggerButton();
  ```
- **Manual Launch from Help/Settings Menu**:
  ```dart
  SnappySnag.startFeedbackMode(context: context);
  ```

---

## 6. Team Roles & AI Credit Safety (SnappySnag Web Dashboard)

SnappySnag enforces a 3-tier role security model:
1. 👑 **Owner**: Full administrative control, pin triage (include/exclude), member invitations, and AI auto-fix code generation.
2. 💻 **Developer**: Technical triage, pin inclusion/exclusion, discussion comments, and AI auto-fix code generation.
3. 🧪 **Tester**: Clean feedback submission, review approved pins. **Cannot exclude pins or consume project AI credits**, preventing unintended billing spikes.

---

## 7. Production Deployment Strategies

### Strategy A: Live In-App User Feedback (Default & Recommended)
SnappySnag works out-of-the-box in production releases. Floating buttons default to hidden (`showTriggerButton: false`), and Release mode automatically suppresses internal duplicate warnings & tickets. You simply trigger it from your settings or help menu:

```dart
SnappySnag.startFeedbackMode(context: context);
```

### Strategy B: Internal Testing Only (Complete Production Shutdown)
If your project policy requires the SDK to be completely dormant in public store releases:

```dart
// Option 1: Completely disabled in Release builds (Zero configuration)
SnappySnag().initialize(
  apiKey: 'YOUR_API_KEY',
  enabled: !kReleaseMode,
);

// Option 2: Enabled only for TestFlight / QA builds using build flags
// flutter build ipa --dart-define=ENABLE_SNAPPY_SNAG=true
const bool isTesting = bool.fromEnvironment('ENABLE_SNAPPY_SNAG', defaultValue: false);
SnappySnag().initialize(
  apiKey: 'YOUR_API_KEY',
  enabled: isTesting,
);
```

---

## 8. Real-Time Team Notifications (Slack & Discord)

When bug reports or user feedback are submitted, SnappySnag instantly dispatches rich webhook notifications:
- **Slack**: Block Kit card formatted with issue summary, severity tag, platform/device metadata, and a direct button opening the ticket.
- **Discord**: Color-coded Embed card with structured fields and a direct ticket deep-link.
- **Security & Privacy**:
  - Webhook URLs are encrypted at rest using AES-256-GCM.
  - End-user privacy is safeguarded by excluding raw screenshot graphics from public channels; authenticated deep-links are provided instead.
- **Setup**: Configured in **Web Dashboard** > **Project Settings** > **Team Notifications** with one-click test sends and automatic configuration saves.