InsurScan.Sdk 0.1.0-alpha.10

InsurScan SDK

Official .NET SDK for InsurScan API - Convert insurance policy and quote PDFs to structured JSON with zero setup. Stateless, secure, and developer-friendly.

Features

• 🚀 Zero Setup - No training, no configuration files, just plug and play
• 📄 PDF to JSON - Convert insurance PDFs to structured, typed data
• 🏢 Multi-Insurance Support - Works with major Turkish insurance companies
• 🔒 Stateless & Secure - No data storage, process and forget
• 🛡️ Type Safe - Full C# type safety with discriminated unions
• 📊 Structured Logging - Comprehensive logging with structured data
• 🔄 Resilient - Built-in retry policies and timeout handling
• ⚡ High Performance - Optimized for speed and efficiency

Installation

Install the NuGet package:

dotnet add package InsurScan.Sdk

Or via Package Manager Console:

Install-Package InsurScan.Sdk

Quick Start

1. Register Services

using InsurScan.Sdk;

// In Program.cs or Startup.cs
builder.Services.AddInsurScan("https://api.insurscan.com");

// Or with configuration
builder.Services.AddInsurScan(builder.Configuration.GetSection("InsurScan"));

2. Configuration (appsettings.json)

{
  "InsurScan": {
    "BaseUrl": "https://api.insurscan.com",
    "Timeout": "00:00:30",
    "MaxFileSize": 5000000,
    "MaxRetryAttempts": 3,
    "BaseDelaySeconds": 1.0
  }
}

3. Use the Client

using InsurScan.Sdk;
using InsurScan.Models;

public class InsuranceService
{
    private readonly IInsurScanClient _insurScanClient;
    private readonly ILogger<InsuranceService> _logger;

    public InsuranceService(IInsurScanClient insurScanClient, ILogger<InsuranceService> logger)
    {
        _insurScanClient = insurScanClient;
        _logger = logger;
    }

    public async Task<KaskoQuoteResult?> ProcessKaskoQuoteAsync(string filePath)
    {
        // Create PDF content from file
        using var pdfContent = PdfContent.FromFile(filePath);

        // Process the PDF
        var result = await _insurScanClient.ReadQuotePdf(
            PdfProductBranch.Kasko,
            pdfContent,
            InsuranceCompany.Auto // Auto-detect insurance company
        );

        // Handle the result
        return result switch
        {
            InsurScanResult<KaskoQuoteResult>.Success success => success.Data,
            InsurScanResult<KaskoQuoteResult>.Failure failure => 
            {
                _logger.LogError("Failed to process PDF: {Error}", failure.Error);
                return null;
            }
        };
    }
}

Usage Examples

Processing from Different Sources

From File Path

using var pdfContent = PdfContent.FromFile("path/to/kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From Stream

using var fileStream = File.OpenRead("kasko-quote.pdf");
using var pdfContent = PdfContent.FromStream(fileStream, "kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From Byte Array

byte[] pdfBytes = await File.ReadAllBytesAsync("kasko-quote.pdf");
using var pdfContent = PdfContent.FromBytes(pdfBytes, "kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From HTTP Upload (ASP.NET Core)

[HttpPost("upload")]
public async Task<IActionResult> UploadKaskoQuote(IFormFile file)
{
    using var stream = file.OpenReadStream();
    using var pdfContent = PdfContent.FromStream(stream, file.FileName);
    
    var result = await _insurScanClient.ReadQuotePdf(
        PdfProductBranch.Kasko, 
        pdfContent,
        InsuranceCompany.Auto
    );

    return result switch
    {
        InsurScanResult<KaskoQuoteResult>.Success success => Ok(success.Data),
        InsurScanResult<KaskoQuoteResult>.Failure failure => BadRequest(failure.Error.ToString())
    };
}

Error Handling

The SDK uses discriminated unions for type-safe error handling:

var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

switch (result)
{
    case InsurScanResult<KaskoQuoteResult>.Success success:
        // Process successful result
        var quote = success.Data;
        Console.WriteLine($"Premium: {quote.Premium.TotalPremium}");
        break;

    case InsurScanResult<KaskoQuoteResult>.Failure failure:
        // Handle specific errors
        switch (failure.Error)
        {
            case InsurScanError.EmptyPdf:
                Console.WriteLine("PDF file is empty");
                break;
            case InsurScanError.EncryptedPdf:
                Console.WriteLine("PDF file is encrypted");
                break;
            case InsurScanError.UnsupportedInsuranceCompany:
                Console.WriteLine("Insurance company not supported");
                break;
            case InsurScanError.NetworkError:
                Console.WriteLine("Network error occurred");
                break;
            default:
                Console.WriteLine($"Error: {failure.Error}");
                break;
        }
        break;
}

Configuration Options

InsurScanClientOptions

Advanced Configuration

builder.Services.AddInsurScan(options =>
{
    options.BaseUrl = "https://api.insurscan.com";
    options.Timeout = TimeSpan.FromSeconds(60);
    options.MaxFileSize = 5_000_000; // 5MB
    options.MaxRetryAttempts = 5;
    options.BaseDelaySeconds = 2.0;
    options.CustomHeaders.Add("X-API-Key", "your-api-key");
    options.CustomHeaders.Add("X-Client-Version", "1.0.0");
});

Supported Insurance Companies

The SDK supports automatic detection and processing of PDFs from major Turkish insurance companies:

• Auto Detection (InsuranceCompany.Auto) - Automatically detects the insurance company
• Aksigorta (InsuranceCompany.Ak)
• HDI Sigorta (InsuranceCompany.Hdi)
• Neova Sigorta (InsuranceCompany.Neova)
• Ray Sigorta (InsuranceCompany.Ray)
• Sompo Sigorta (InsuranceCompany.Sompo)
• Türkiye Katılım Bankası (InsuranceCompany.TurkiyeKatilim)

Error Types

The SDK defines comprehensive error types for different failure scenarios:

Logging

The SDK provides comprehensive structured logging with the InsurScan prefix for easy filtering:

// Configure logging in Program.cs
builder.Logging.AddConsole();
builder.Logging.SetMinimumLevel(LogLevel.Information);

// Example log output:
// [INF] InsurScan starting PDF quote reading for ProductBranch: Kasko, InsuranceCompany: Auto, FileSize: 245760 bytes, FileName: quote.pdf
// [ERR] InsurScan PDF processing failed with error: UnsupportedInsuranceCompany for ProductBranch: Kasko

Log Levels

• Debug: Detailed flow information, internal operations
• Information: Normal operations, successful processing
• Warning: Validation failures, recoverable errors
• Error: Processing failures, network errors, exceptions

Best Practices

1. Use Dependency Injection

// ✅ Good - Use DI
public class QuoteService
{
    private readonly IInsurScanClient _client;
    
    public QuoteService(IInsurScanClient client) => _client = client;
}

// ❌ Bad - Don't create instances manually
var client = new InsurScanClient(/* ... */);

2. Dispose PDF Content

// ✅ Good - Use using statements
using var pdfContent = PdfContent.FromFile("quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

// ❌ Bad - Memory leaks
var pdfContent = PdfContent.FromFile("quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
// pdfContent not disposed

3. Handle All Error Cases

// ✅ Good - Comprehensive error handling
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
return result switch
{
    InsurScanResult<KaskoQuoteResult>.Success success => success.Data,
    InsurScanResult<KaskoQuoteResult>.Failure failure => HandleError(failure.Error)
};

// ❌ Bad - Ignoring errors
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
return ((InsurScanResult<KaskoQuoteResult>.Success)result).Data; // Can throw!

4. Use Cancellation Tokens

// ✅ Good - Support cancellation
public async Task<KaskoQuoteResult?> ProcessAsync(string filePath, CancellationToken cancellationToken)
{
    using var pdfContent = PdfContent.FromFile(filePath);
    var result = await _client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent, cancellationToken: cancellationToken);
    // ...
}

5. Configure Appropriate Timeouts

// ✅ Good - Set reasonable timeouts based on file sizes
builder.Services.AddInsurScan(options =>
{
    options.Timeout = TimeSpan.FromMinutes(2); // For large files
    options.MaxFileSize = 10_000_000; // 10MB
});

Performance Considerations

• File Size: Keep PDF files under 5MB for optimal performance
• Concurrent Requests: The client is thread-safe and supports concurrent requests
• Memory Usage: Always dispose IPdfContent instances to prevent memory leaks
• Retry Policy: Built-in exponential backoff handles transient failures automatically
• Connection Pooling: Uses HttpClientFactory for efficient connection management

Troubleshooting

Common Issues

1. "PDF file is encrypted"

   • Ensure the PDF is not password-protected
   • Remove encryption before processing

2. "Insurance company not detected"

   • Verify the PDF is from a supported insurance company
   • Check if the PDF format is standard

3. "Network error"

   • Check internet connectivity
   • Verify the API endpoint URL
   • Check firewall settings

4. "Request timeout"

   • Increase the timeout value in configuration
   • Check file size limits

Debug Logging

Enable debug logging to see detailed operation flow:

builder.Logging.SetMinimumLevel(LogLevel.Debug);

Support

• Documentation: https://docs.insurscan.com
• API Reference: https://api.insurscan.com/docs
• Issues: GitHub Issues
• Email: support@insurup.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Made with ❤️ by InsurUp