InsurScan.Sdk 0.1.34

InsurScan SDK

👁 NuGet
👁 Downloads

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 file for details.

Contributing

We welcome contributions! Please see our for details.

Made with ❤️ by InsurUp