# IronServices.Maui

MAUI controls and services for IronServices (IronLicensing, IronNotify, IronTelemetry).

## Installation

```xml
<PackageReference Include="IronServices.Maui" Version="1.0.0" />
```

## Quick Start

### 1. Register Services

```csharp
// MauiProgram.cs
builder.Services.AddIronServices();

// Or with custom URLs
builder.Services.AddIronServices(options =>
{
    options.LicensingUrl = "https://ironlicensing.com";
    options.NotifyUrl = "https://ironnotify.com";
    options.TelemetryUrl = "https://irontelemetry.com";
});
```

### 2. Use Controls

```xaml
<ContentPage xmlns:iron="clr-namespace:IronServices.Maui.Controls;assembly=IronServices.Maui">
    <iron:LoginView Client="{Binding IronClient}" LoginSuccess="OnLoginSuccess" />
</ContentPage>
```

---

## Controls

### LoginView

A drop-in login form for IronServices authentication.

**Type:** `ContentView` (embeddable)

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Client` | `IronServicesClient` | `null` | **Required.** The client instance for authentication. |
| `Title` | `string` | `"Sign In"` | Header text above the form. |
| `Subtitle` | `string` | `"Enter your credentials..."` | Subheader text. |
| `Logo` | `ImageSource` | `null` | Optional logo image. |
| `ShowRegisterLink` | `bool` | `true` | Show "Sign Up" link. |
| `ShowForgotPasswordLink` | `bool` | `true` | Show "Forgot Password?" link. |

#### Events

| Event | Args | Description |
|-------|------|-------------|
| `LoginSuccess` | `LoginSuccessEventArgs` | Fired on successful login. Contains `UserId`, `Email`, `DisplayName`. |
| `LoginFailed` | `LoginFailedEventArgs` | Fired on failed login. Contains `Error` message. |
| `RegisterRequested` | `EventArgs` | User tapped "Sign Up" link. |
| `ForgotPasswordRequested` | `EventArgs` | User tapped "Forgot Password?" link. |

#### Example

```csharp
// XAML
<iron:LoginView x:Name="LoginView"
                Client="{Binding IronClient}"
                Title="Welcome Back"
                Logo="logo.png"
                ShowRegisterLink="True"
                LoginSuccess="OnLoginSuccess"
                RegisterRequested="OnRegisterRequested" />

// Code-behind
private async void OnLoginSuccess(object sender, LoginSuccessEventArgs e)
{
    await DisplayAlert("Success", $"Welcome, {e.DisplayName}!", "OK");
    await Shell.Current.GoToAsync("//main");
}

private async void OnRegisterRequested(object sender, EventArgs e)
{
    await Shell.Current.GoToAsync("//register");
}
```

---

### LicenseActivationView

A license key entry and activation form.

**Type:** `ContentView` (embeddable)

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `LicenseManager` | `ILicenseManager` | `null` | **Required.** The license manager instance. |
| `Title` | `string` | `"Activate License"` | Header text. |
| `Subtitle` | `string` | `"Enter your license key..."` | Subheader text. |
| `LicenseKey` | `string` | `null` | Pre-filled license key (two-way binding). |
| `ShowHelpLink` | `bool` | `true` | Show help link below form. |
| `HelpUrl` | `string` | `"https://..."` | URL opened when help tapped. |

#### Events

| Event | Args | Description |
|-------|------|-------------|
| `LicenseActivated` | `LicenseActivatedEventArgs` | Activation succeeded. Contains `License` info. |
| `ActivationFailed` | `LicenseActivationFailedEventArgs` | Activation failed. Contains `Error` message. |
| `HelpRequested` | `EventArgs` | User tapped help link. |

#### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `ValidateAsync()` | `Task<bool>` | Validate the entered license key without activating. |

#### Example

```csharp
// XAML
<iron:LicenseActivationView x:Name="ActivationView"
                            LicenseManager="{Binding LicenseManager}"
                            LicenseActivated="OnLicenseActivated" />

// Code-behind
private async void OnLicenseActivated(object sender, LicenseActivatedEventArgs e)
{
    var license = e.License;
    await DisplayAlert("Activated",
        $"License: {license.Tier}\nExpires: {license.ExpiresAt:d}", "OK");
}
```

---

### AppLogView

A full-page log viewer for exceptions and telemetry events. Shows queued items from `TelemetryClient.OfflineQueue`.

**Type:** `ContentPage` (standalone page, use with NavigationPage)

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `TelemetryClient` | `TelemetryClient` | `null` | Client to pull queued logs from. Auto-refreshes on set. |
| `Title` | `string` | `"App Logs"` | Page title (shown in navigation bar). |
| `ShowShareButton` | `bool` | `true` | Enable Share toolbar button. |
| `ShowClearButton` | `bool` | `true` | Enable Clear toolbar button. |

#### Events

| Event | Args | Description |
|-------|------|-------------|
| `LogsCleared` | `EventArgs` | User cleared the log list. |
| `LogsShared` | `EventArgs` | User shared the logs. |
| `LogSelected` | `LogItem` | User selected a log entry. |
| `LogsRefreshed` | `EventArgs` | Log list was refreshed. |

#### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `RefreshLogs()` | `void` | Reload logs from TelemetryClient queue. |
| `AddLog(type, title, message, stackTrace?)` | `void` | Add a manual log entry. |
| `AddException(Exception)` | `void` | Add an exception as a log entry. |
| `ClearLogs()` | `void` | Clear displayed logs (not the queue). |
| `ClearAllLogs()` | `void` | Clear displayed logs AND the offline queue. |
| `ExportLogs()` | `string` | Export all logs as formatted text. |
| `GetLogs()` | `IReadOnlyList<LogItem>` | Get current log items. |
| `LogCount` | `int` | Number of log items. |

#### LogItem Properties

| Property | Type | Description |
|----------|------|-------------|
| `Timestamp` | `DateTime` | UTC timestamp. |
| `Type` | `string` | `"exception"`, `"message"`, `"info"`, `"warning"`, etc. |
| `Title` | `string` | Exception type name or message title. |
| `Message` | `string` | Log message. |
| `StackTrace` | `string?` | Stack trace for exceptions. |
| `JourneyId` | `string?` | Associated user journey ID. |
| `UserId` | `string?` | Associated user ID. |

#### Example

```csharp
// Navigate to log view
await Navigation.PushAsync(new AppLogView
{
    TelemetryClient = _telemetryClient,
    Title = "Error Logs"
});

// With event handling
var logView = new AppLogView { TelemetryClient = _telemetryClient };
logView.LogsCleared += (s, e) => Debug.WriteLine("Logs cleared");
logView.LogSelected += (s, item) => Debug.WriteLine($"Selected: {item.Title}");
await Navigation.PushAsync(logView);

// Manual log entries (without TelemetryClient)
var logView = new AppLogView();
logView.AddException(ex);
logView.AddLog("warning", "Network Issue", "Connection timeout after 30s");
```

#### Toolbar

- **Share** (Primary): Exports logs as text and opens system share sheet.
- **Clear** (Secondary/overflow menu): Clears displayed logs.
- **Refresh** button in summary bar: Reloads from queue.

---

## Services

### MauiSecureTokenStorage

Secure token storage using MAUI `SecureStorage`. Automatically registered when using `AddIronServices()`.

```csharp
// Automatically used by IronServicesClient
builder.Services.AddIronServices();

// Or manually
services.AddSingleton<ITokenStorage, MauiSecureTokenStorage>();
```

### ServiceCollectionExtensions

```csharp
// Default URLs
services.AddIronServices();

// Custom URLs
services.AddIronServices(options =>
{
    options.LicensingUrl = "https://licensing.myapp.com";
    options.NotifyUrl = "https://notify.myapp.com";
    options.TelemetryUrl = "https://telemetry.myapp.com";
});
```

Registers:
- `MauiSecureTokenStorage` as `ITokenStorage`
- `IronServicesClient` as singleton

---

## Complete Example

```csharp
// MauiProgram.cs
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder.UseMauiApp<App>();

    // Register IronServices
    builder.Services.AddIronServices();

    // Register TelemetryClient for logging
    builder.Services.AddSingleton(sp => new TelemetryClient(new TelemetryOptions
    {
        Dsn = "your-dsn-here",
        EnableOfflineQueue = true
    }));

    return builder.Build();
}

// LoginPage.xaml
<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:iron="clr-namespace:IronServices.Maui.Controls;assembly=IronServices.Maui">
    <ScrollView>
        <iron:LoginView x:Name="LoginControl"
                        Client="{Binding IronClient}"
                        Logo="app_logo.png"
                        Title="Welcome"
                        LoginSuccess="OnLoginSuccess" />
    </ScrollView>
</ContentPage>

// LoginPage.xaml.cs
public partial class LoginPage : ContentPage
{
    public LoginPage(IronServicesClient client)
    {
        InitializeComponent();
        LoginControl.Client = client;
    }

    private async void OnLoginSuccess(object sender, LoginSuccessEventArgs e)
    {
        await Shell.Current.GoToAsync("//main");
    }
}

// SettingsPage.xaml.cs - Navigate to logs
private async void OnViewLogsClicked(object sender, EventArgs e)
{
    var telemetry = Handler.MauiContext.Services.GetService<TelemetryClient>();
    await Navigation.PushAsync(new AppLogView
    {
        TelemetryClient = telemetry
    });
}
```

---

## Styling

All controls use MAUI resource dictionaries. Override these colors in your `App.xaml`:

```xaml
<Color x:Key="Primary">#512BD4</Color>
<Color x:Key="Secondary">#DFD8F7</Color>
<Color x:Key="Gray100">#E1E1E1</Color>
<Color x:Key="Gray200">#C8C8C8</Color>
<Color x:Key="Gray400">#919191</Color>
<Color x:Key="Gray500">#6E6E6E</Color>
<Color x:Key="Gray600">#404040</Color>
<Color x:Key="Gray900">#212121</Color>
<Color x:Key="White">#FFFFFF</Color>
```

Controls support light/dark themes via `AppThemeBinding`.

---

## Platform Support

| Platform | Minimum Version |
|----------|-----------------|
| Android | API 21 (5.0) |
| iOS | 14.0 |
| macOS | 11.0 |
| Windows | 10.0.17763.0 |

---

## Dependencies

- `IronServices.Client` - Core API client
- `IronLicensing.Client` - License validation
- `IronTelemetry.Client` - Telemetry and logging
- `Microsoft.Maui.Controls` - MAUI framework

---

## License

Proprietary. See LICENSE file.