Documentors.Sdk 0.1.2

DocuMentors C# SDK

Official .NET SDK for the DocuMentors DDAS API (Document Detection & Analysis System).

Features

• Document Management — Upload, download, version tracking, classification
• PII Detection — Scan for 24+ PII types (email, phone, SSN, credit card, etc.)
• Phishing Analysis — Email and URL threat detection with confidence scoring
• Compliance — Legal holds, retention policies, audit logging
• Security — API key management, user administration, role-based access
• Robust Transport — Automatic retry with exponential backoff, timeout handling
• Typed Models — C# records for full compile-time type safety
• Error Handling — 7 specific exception types with detailed status codes

Requirements

• .NET 8.0+ (or .NET 6.0+ with framework adjustments)
• Valid API key or Bearer token
• Network access to DDAS API

Installation

# From NuGet (when published)
dotnet add package Documentors.Sdk

# Or from local build
dotnet add reference ../sdk/csharp/src/Documentors.Sdk.csproj

Quick Start

using Documentors.Sdk;

// Create a client with your API key
using var client = new DocumentorsClient("ddas_standard_your_key_here");

// Health check
var health = await client.HealthAsync();
Console.WriteLine($"API status: {health.Status}");

// Upload & scan a document
var doc = await client.Documents.UploadAsync("contract.pdf", File.ReadAllBytes("contract.pdf"));
var scan = await client.Security.ScanAsync(doc.Id);

foreach (var detection in scan.Detections)
    Console.WriteLine($"  {detection.DetectorName}: {detection.RedactedPreview} (confidence: {detection.ConfidenceScore:P0})");

Configuration

using var client = new DocumentorsClient(new DocumentorsClientOptions
{
    ApiKey = "ddas_standard_...",
    BaseUrl = "https://your-spoke.example.com",
    Timeout = TimeSpan.FromSeconds(60),
    MaxRetries = 5,
    BaseBackoff = TimeSpan.FromSeconds(2),
});

Configuration Options

Resources

Documents

Document upload, retrieval, versioning, and lifecycle management.

// List documents
var docs = await client.Documents.ListAsync(page: 1, pageSize: 20);

// Upload a document
var doc = await client.Documents.UploadAsync(
    filename: "contract.pdf",
    content: fileBytes,
    contentType: "application/pdf",
    classification: "CONFIDENTIAL");

// Get document details
var info = await client.Documents.GetAsync(doc.Id);

// Download document content
var content = await client.Documents.DownloadAsync(doc.Id);

// List document versions
var versions = await client.Documents.GetVersionsAsync(doc.Id);

// Delete a document
await client.Documents.DeleteAsync(doc.Id);

Classification Levels:

• UNCLASSIFIED (default)
• CUI (Controlled Unclassified Information)
• CONFIDENTIAL
• SECRET
• TOP SECRET

Security

PII detection, document scanning, and phishing analysis.

// Scan document for PII
var scan = await client.Security.ScanAsync(
    documentId: doc.Id,
    detectors: new[] { "email", "phone", "ssn" });

// Get previous scan results
var results = await client.Security.GetScanResultsAsync(doc.Id);

// Get scan history
var history = await client.Security.GetScanHistoryAsync(doc.Id);

// Redact detected PII
var redaction = await client.Security.RedactAsync(
    documentId: doc.Id,
    detectionTypes: new[] { "EMAIL", "PHONE" });

// Analyze email for phishing
var emailAnalysis = await client.Security.AnalyzeEmailAsync(
    subject: "Click here to verify",
    body: "Click now!",
    senderEmail: "attacker@fake.com",
    headers: new[] { "X-Mailer: Unknown" });

// Analyze URL for threats
var urlAnalysis = await client.Security.AnalyzeUrlAsync("https://suspicious.example.com");

// Batch URL analysis
var urls = new[] { "https://example.com", "https://another.com" };
var analyses = await client.Security.AnalyzeUrlsAsync(urls);

Detection Types:

• EMAIL, PHONE, SSN, CREDIT_CARD
• PASSPORT, DRIVER_LICENSE, BANK_ACCOUNT
• LATITUDE, LONGITUDE, IP_ADDRESS
• And 15+ more (24 total)

Phishing Verdicts:

• safe — No phishing indicators detected
• suspicious — Some indicators present, requires investigation
• malicious — High confidence phishing/malware detected

Compliance

Legal holds, retention policies, and eDiscovery management.

// List legal holds
var holds = await client.Compliance.ListLegalHoldsAsync();

// Create a legal hold
var hold = await client.Compliance.CreateLegalHoldAsync(
    name: "Smith v. Jones Litigation",
    documentIds: new[] { "doc-001", "doc-002" });

// Get hold details
var holdDetail = await client.Compliance.GetLegalHoldAsync(hold.Id);

// Release a legal hold
await client.Compliance.DeleteLegalHoldAsync(hold.Id);

// List retention policies
var policies = await client.Compliance.ListRetentionPoliciesAsync();

// Create retention policy
var policy = await client.Compliance.CreateRetentionPolicyAsync(
    name: "Financial Records",
    retentionDays: 2555,  // 7 years
    action: "archive");   // or "delete"

Admin

API key management, user administration, and audit logs.

// List API keys
var keys = await client.Admin.ListApiKeysAsync();

// Create an API key
var key = await client.Admin.CreateApiKeyAsync(
    name: "Customer ABC",
    tier: "premium",
    scopes: new[] { "detect", "redact", "compliance" },
    expiresAt: DateTime.UtcNow.AddMonths(12).ToString("O"));

// Revoke an API key
await client.Admin.RevokeApiKeyAsync(key.Id);

// List users
var users = await client.Admin.ListUsersAsync();

// Get user details
var user = await client.Admin.GetUserAsync(users[0].Id);

// Query audit logs
var logs = await client.Admin.GetAuditLogsAsync(
    action: "document_upload",
    actor: "user@example.com",
    since: DateTime.UtcNow.AddDays(-7).ToString("O"),
    limit: 100);

API Tiers:

• standard — Basic detection and document management
• premium — All features + compliance and admin access
• enterprise — Custom deployments with SLA guarantees

Error Handling

The SDK provides 7 specific exception types for different error scenarios:

try
{
    await client.Documents.GetAsync("missing-id");
}
catch (AuthenticationException ex)
{
    Console.WriteLine("❌ Invalid API key or token");
}
catch (PermissionDeniedException ex)
{
    Console.WriteLine("❌ Insufficient permissions for this operation");
    Console.WriteLine($"Required scope: {ex.RequiredScope}");
}
catch (NotFoundException ex)
{
    Console.WriteLine("❌ Resource not found");
}
catch (ConflictException ex)
{
    Console.WriteLine("❌ Conflict (e.g., duplicate name)");
}
catch (ValidationException ex)
{
    Console.WriteLine("❌ Validation error");
    if (ex.Errors != null)
    {
        foreach (var error in ex.Errors)
            Console.WriteLine($"  • {error.Field}: {error.Message}");
    }
}
catch (RateLimitException ex)
{
    Console.WriteLine($"⏱️  Rate limited. Retry after {ex.RetryAfter}s");
}
catch (ServerException ex)
{
    Console.WriteLine($"🔴 Server error ({ex.StatusCode})");
}
catch (NetworkException ex)
{
    Console.WriteLine("🌐 Network connectivity issue");
}
catch (TimeoutException ex)
{
    Console.WriteLine("⏰ Request timed out");
}
catch (DocumentorsException ex)
{
    // Catch-all for any other errors
    Console.WriteLine($"Error: {ex.Message}");
}

Retry & Backoff

The SDK automatically retries transient failures (429, 5xx) with exponential backoff:

// Configuration
using var client = new DocumentorsClient(new DocumentorsClientOptions
{
    ApiKey = "your_key",
    MaxRetries = 5,                    // Retry up to 5 times
    BaseBackoff = TimeSpan.FromSeconds(1),  // Start with 1s
});

// Retry schedule: 1s, 2s, 4s, 8s, 16s (exponential)
// After 5 attempts, throws ServerException or RateLimitException

Examples

See the examples/ directory for complete working examples:

• BasicUsage.cs — Document upload and scanning
• SecurityAnalysis.cs — Phishing detection and threat analysis
• ComplianceManagement.cs — Legal holds and retention policies
• AdminOperations.cs — API keys, users, and audit logs
• ErrorHandling.cs — Comprehensive error handling patterns

Development

Building from Source

cd csharp
dotnet build

Running Tests

dotnet test tests/

Tests Included

• 40+ unit tests covering all resources
• Exception handling and error mapping
• Retry logic and backoff testing
• Mock HTTP transport validation

Project Structure

csharp/
├── src/
│   ├── DocumentorsClient.cs         # Main client class
│   ├── DocumentorsClientOptions.cs  # Configuration
│   ├── DocumentsResource.cs         # Document operations
│   ├── SecurityResource.cs          # PII & phishing detection
│   ├── ComplianceResource.cs        # Legal holds & retention
│   ├── AdminResource.cs             # API keys, users, audit
│   ├── Models.cs                    # Data models (records)
│   ├── Transport.cs                 # HTTP transport layer
│   ├── Exceptions.cs                # Exception types
│   └── Documentors.Sdk.csproj       # Project file
├── tests/
│   ├── SdkTests.cs                  # Comprehensive test suite
│   └── Documentors.Sdk.Tests.csproj # Test project
├── examples/
│   ├── BasicUsage.cs
│   ├── SecurityAnalysis.cs
│   ├── ComplianceManagement.cs
│   ├── AdminOperations.cs
│   ├── ErrorHandling.cs
│   └── README.md
├── Documentors.Sdk.sln              # Solution file
└── README.md                        # This file

API Reference

Authentication

The SDK supports two authentication methods:

1. API Key (recommended for production)

   var client = new DocumentorsClient(new DocumentorsClientOptions
   {
       ApiKey = "ddas_standard_abc123...",
   });
   

2. Bearer Token (JWT)

   var client = new DocumentorsClient(new DocumentorsClientOptions
   {
       BearerToken = "eyJhbGc...",
   });
   

Request Formats

All requests use JSON with snake_case property names:

// Uploaded as: {"filename":"test.pdf","content":"...","classification":"CONFIDENTIAL"}
var doc = await client.Documents.UploadAsync(
    filename: "test.pdf",
    content: bytes,
    classification: "CONFIDENTIAL");

Response Formats

All responses use snake_case property names (automatically converted to PascalCase):

// Response: {"scan_id":"...", "document_id":"...", ...}
var scan = await client.Security.ScanAsync(docId);
Console.WriteLine(scan.ScanId);        // PascalCase property

Performance & Scaling

• Concurrent Requests: Use multiple client instances or async/await in parallel
• Large Files: Use streams for upload/download (implement if needed)
• Rate Limiting: Default 100 req/min for standard tier, configurable per key
• Timeouts: Default 30s, increase for slow networks or large files
• Connection Pooling: HttpClient handles pooling automatically

Security Best Practices

1. API Keys

   • Never hardcode keys in source
   • Use environment variables or secure vaults
   • Rotate keys regularly
   • Use minimal required scopes

2. Classification

   • Mark documents with appropriate levels
   • Enforce retention policies for classified data
   • Audit access to sensitive documents

3. Transport

   • Always use HTTPS (enabled by default)
   • Verify certificates in production
   • Use custom HttpClient for proxy/certificate pinning if needed

4. Error Messages

   • Don't log full error responses (may contain sensitive data)
   • Log error type and status code only
   • Include exception context for debugging

Licensing

MIT License — See LICENSE file

Support

• Documentation: https://docs.docu-mentors.com/sdk/csharp
• Issues: https://github.com/docu-mentors/sdk-csharp/issues
• Email: support@docu-mentors.com

Changelog

v0.1.0 (2024)

• Initial release
• 4 resource modules (Documents, Security, Compliance, Admin)
• 40+ tests, 5 example files
• Automatic retry with exponential backoff
• 7 exception types with detailed error mapping
• Full TypeScript/C# type coverage

var list = await client.Documents.ListAsync(page: 1, pageSize: 50);
var doc = await client.Documents.GetAsync("doc-id");
var uploaded = await client.Documents.UploadAsync("file.pdf", bytes);
await client.Documents.DeleteAsync("doc-id");
var versions = await client.Documents.GetVersionsAsync("doc-id");
byte[] content = await client.Documents.DownloadAsync("doc-id");

Security

// PII scan
var scan = await client.Security.ScanAsync("doc-id");
var results = await client.Security.GetScanResultsAsync("doc-id");
var history = await client.Security.GetScanHistoryAsync("doc-id");
var redacted = await client.Security.RedactAsync("doc-id");

// Phishing
var email = await client.Security.AnalyzeEmailAsync("Subject", "Body", "sender@example.com");
var url = await client.Security.AnalyzeUrlAsync("https://suspicious.example.com");

Compliance

var holds = await client.Compliance.ListLegalHoldsAsync();
var hold = await client.Compliance.CreateLegalHoldAsync("Investigation A", docIds);
await client.Compliance.DeleteLegalHoldAsync("hold-id");
var policies = await client.Compliance.ListRetentionPoliciesAsync();

Admin

var keys = await client.Admin.ListApiKeysAsync();
var newKey = await client.Admin.CreateApiKeyAsync("CI Pipeline", tier: "standard");
await client.Admin.RevokeApiKeyAsync("key-id");
var users = await client.Admin.ListUsersAsync();
var logs = await client.Admin.GetAuditLogsAsync(action: "document.upload", limit: 50);

Error Handling

The SDK throws typed exceptions:

try
{
    var doc = await client.Documents.GetAsync("nonexistent");
}
catch (NotFoundException ex)
{
    Console.WriteLine($"Not found: {ex.Detail}");
}
catch (RateLimitException ex)
{
    Console.WriteLine($"Rate limited. Retry after {ex.RetryAfter}s");
}

Retry Behavior

Transient errors (429, 500, 502, 503, 504) are automatically retried with exponential backoff. Configure via MaxRetries and BaseBackoff in options.

License

Proprietary — DocuMentors Platform