viewengine.client/QUICKSTART.md

# ViewEngine.Client - Quick Start Guide

## Installation

```bash
dotnet add package ViewEngine.Client
```

## 30-Second Quick Start

```csharp
using ViewEngine.Client;
using ViewEngine.Client.Models;

var client = new ViewEngineClient("ak_your-api-key-here");

var pageData = await client.RetrieveAndWaitAsync(new SubmitRetrievalRequest
{
    Url = "https://example.com"
});

Console.WriteLine($"Title: {pageData.Title}");
Console.WriteLine($"Content: {pageData.Body}");
```

## Common Use Cases

### 1. Simple Page Retrieval
```csharp
var client = new ViewEngineClient("ak_your-api-key-here");
var page = await client.RetrieveAndWaitAsync(new SubmitRetrievalRequest
{
    Url = "https://example.com"
});
```

### 2. With ASP.NET Core DI

**appsettings.json:**
```json
{
  "ViewEngine": {
    "ApiKey": "ak_your-api-key-here"
  }
}
```

**Program.cs:**
```csharp
builder.Services.AddViewEngineClient(builder.Configuration);
```

**Usage:**
```csharp
public class MyController : ControllerBase
{
    private readonly ViewEngineClient _client;

    public MyController(ViewEngineClient client) => _client = client;

    [HttpGet]
    public async Task<IActionResult> GetPage(string url)
    {
        var page = await _client.RetrieveAndWaitAsync(new SubmitRetrievalRequest { Url = url });
        return Ok(page);
    }
}
```

### 3. Custom Platform Selection
```csharp
var page = await client.RetrieveAndWaitAsync(new SubmitRetrievalRequest
{
    Url = "https://example.com",
    PreferredPlatform = "Windows"  // or "Android", "iOS"
});
```

### 4. High Priority Job
```csharp
var page = await client.RetrieveAndWaitAsync(new SubmitRetrievalRequest
{
    Url = "https://example.com",
    Priority = 10  // 1-10, higher = faster (costs more)
});
```

### 5. Manual Polling
```csharp
var response = await client.SubmitRetrievalAsync(new SubmitRetrievalRequest
{
    Url = "https://example.com"
});

RetrievalStatusResponse status;
do
{
    await Task.Delay(2000);
    status = await client.GetRetrievalStatusAsync(response.RequestId);
} while (status.Status != "complete" && status.Status != "failed");

if (status.Status == "complete")
{
    var page = await client.GetPageContentAsync(response.RequestId);
}
```

## Key Features

| Feature | Method |
|---------|--------|
| Submit retrieval | `SubmitRetrievalAsync()` |
| Check status | `GetRetrievalStatusAsync()` |
| Get content | `GetPageContentAsync()` |
| Submit & wait | `RetrieveAndWaitAsync()` |
| Add client | `AddClientAsync()` |
| List clients | `GetClientsAsync()` |
| Client stats | `GetClientStatsAsync()` |

## Page Data Structure

```csharp
public class PageData
{
    string Title                     // Page title
    string Body                      // Full text content
    string MetaDescription           // Meta description
    string Url                       // Final URL after redirects
    string FaviconUrl                // Favicon URL
    string Thumbnail                 // Base64 PNG screenshot
    List<LinkInfo> Routes            // Navigation links
    List<LinkInfo> BodyRoutes        // Content links
}
```

## Error Handling

```csharp
try
{
    var page = await client.RetrieveAndWaitAsync(request);
}
catch (HttpRequestException ex)
{
    // Network/HTTP errors
}
catch (InvalidOperationException ex)
{
    // Retrieval failed
}
catch (OperationCanceledException)
{
    // Request canceled
}
```

## Configuration Options

```csharp
var options = new ViewEngineOptions
{
    ApiKey = "ak_your-api-key-here",
    BaseUrl = "https://www.viewengine.io/api/v1",
    TimeoutSeconds = 120,
    MaxRetries = 3,
    DefaultPollingIntervalMs = 2000
};

var client = new ViewEngineClient(options);
```

## Request Options

```csharp
var request = new SubmitRetrievalRequest
{
    Url = "https://example.com",
    TimeoutSeconds = 60,           // Max: 300
    ForceRefresh = false,          // Bypass cache
    Priority = 5,                  // 1-10
    PreferredPlatform = "Windows", // Android, iOS, Windows
    ClientId = clientGuid,         // Route to specific client
    CustomUserId = "custom-id"     // Or use custom ID
};
```

## Need More Help?

- Full Documentation: `README.md`
- Code Examples: `Examples.md`
- API Docs: https://www.viewengine.io/docs
- GitHub: https://github.com/marketally/viewengine