.NET SDK

NuGet version .NET Licence: MIT

Per-endpoint request and response samples are in the API reference.

Installation

Install the package using the .NET CLI:

dotnet add package Neuwo.Api

Or via the NuGet Package Manager Console:

Install-Package Neuwo.Api

Or add it directly to your .csproj file:

<PackageReference Include="Neuwo.Api" Version="0.1.0" />

Requirements

This SDK supports:

Platform Support

The SDK is cross-platform and works on:

Dependencies

Note: The SDK uses HttpClient for all HTTP operations and supports modern .NET features including nullable reference types and async/await patterns.

Quick Start

REST API Client

using Neuwo.Api.Clients;
using Neuwo.Api.Configuration;

// Initialise client
var options = new NeuwoRestClientOptions
{
    Token = "your-rest-api-token",
    BaseUrl = "https://custom.api.com"
};

using var client = new NeuwoRestClient(options);

// Analyse text content
var response = await client.GetAiTopicsAsync(
    content: "Cats make wonderful pets for modern households.",
    documentId: "article-123",
    headline: "Why Cats Make Great Pets"
);

// Access results
Console.WriteLine($"Tags: {response.Tags.Count}");
foreach (var tag in response.Tags)
{
    Console.WriteLine($"  - {tag.Value} (score: {tag.Score:F4})");
}

Console.WriteLine($"Brand Safe: {response.BrandSafety.IsSafe}");
Console.WriteLine($"IAB Categories: {response.MarketingCategories.IabTier1.Count}");

EDGE API Client

using Neuwo.Api.Clients;
using Neuwo.Api.Configuration;

// Initialise client
var options = new NeuwoEdgeClientOptions
{
    Token = "your-edge-api-token",
    BaseUrl = "https://custom.api.com",
    DefaultOrigin = "https://yourwebsite.com" // Optional: default origin for requests
};

using var client = new NeuwoEdgeClient(options);

// Analyse article by URL
var response = await client.GetAiTopicsAsync(url: "https://example.com/article");

// Or wait for analysis to complete (with automatic retry)
var responseWithWait = await client.GetAiTopicsWaitAsync(
    url: "https://example.com/new-article",
    maxRetries: 10,
    retryInterval: 6
);

Console.WriteLine($"Found {responseWithWait.Tags.Count} tags for the article");

Configuration

REST Client Parameters

Parameter Type Default Description
Token string Required REST API authentication token
BaseUrl string Required Base URL for the API
Timeout int 60 Request timeout in seconds
Logger ILogger<NeuwoRestClient> null Optional logger instance

Example:

var options = new NeuwoRestClientOptions
{
    Token = "your-token",
    BaseUrl = "https://custom.api.com",
    Timeout = 120
};

using var client = new NeuwoRestClient(options);

EDGE Client Parameters

Parameter Type Default Description
Token string Required EDGE API authentication token
BaseUrl string Required Base URL for the API
Timeout int 60 Request timeout in seconds
DefaultOrigin string null Default Origin header for requests
Logger ILogger<NeuwoEdgeClient> null Optional logger instance

Example:

var options = new NeuwoEdgeClientOptions
{
    Token = "your-token",
    BaseUrl = "https://custom.api.com",
    DefaultOrigin = "https://yoursite.com",
    Timeout = 90
};

using var client = new NeuwoEdgeClient(options);

Dependency Injection

The SDK works seamlessly with .NET's built-in Dependency Injection:

ASP.NET Core Integration

using Neuwo.Api.Clients;
using Neuwo.Api.Configuration;

var builder = WebApplication.CreateBuilder(args);

// Register REST client
builder.Services.AddSingleton<NeuwoRestClient>(sp =>
{
    var logger = sp.GetRequiredService<ILogger<NeuwoRestClient>>();
    var options = new NeuwoRestClientOptions
    {
        Token = builder.Configuration["Neuwo:RestToken"],
        BaseUrl = builder.Configuration["Neuwo:BaseUrl"],
        Logger = logger
    };
    return new NeuwoRestClient(options);
});

// Register EDGE client
builder.Services.AddSingleton<NeuwoEdgeClient>(sp =>
{
    var logger = sp.GetRequiredService<ILogger<NeuwoEdgeClient>>();
    var options = new NeuwoEdgeClientOptions
    {
        Token = builder.Configuration["Neuwo:EdgeToken"],
        BaseUrl = builder.Configuration["Neuwo:BaseUrl"],
        DefaultOrigin = builder.Configuration["Neuwo:DefaultOrigin"],
        Logger = logger
    };
    return new NeuwoEdgeClient(options);
});

var app = builder.Build();

Usage in Controllers

using Microsoft.AspNetCore.Mvc;
using Neuwo.Api.Clients;

[ApiController]
[Route("api/[controller]")]
public class ContentController : ControllerBase
{
    private readonly NeuwoRestClient _neuwoClient;
    private readonly ILogger<ContentController> _logger;

    public ContentController(NeuwoRestClient neuwoClient, ILogger<ContentController> logger)
    {
        _neuwoClient = neuwoClient;
        _logger = logger;
    }

    [HttpPost("analyse")]
    public async Task<IActionResult> AnalyseContent([FromBody] string content)
    {
        try
        {
            var response = await _neuwoClient.GetAiTopicsAsync(content: content);
            return Ok(response);
        }
        catch (NeuwoApiException ex)
        {
            _logger.LogError(ex, "Failed to analyse content");
            return StatusCode((int?)ex.StatusCode ?? 500, ex.Message);
        }
    }
}

Configuration via appsettings.json

{
  "Neuwo": {
    "RestToken": "your-rest-token",
    "EdgeToken": "your-edge-token",
    "BaseUrl": "https://api.neuwo.ai",
    "DefaultOrigin": "https://yourwebsite.com"
  }
}

API Methods

REST API

Get AI Topics

var response = await client.GetAiTopicsAsync(
    content: "Text to analyse",               // Required
    documentId: "doc123",                     // Optional: save to database
    lang: "en",                               // Optional: ISO 639-1 code
    publicationId: "pub1",                    // Optional
    headline: "Article Headline",             // Optional
    tagLimit: 15,                             // Optional: max tags (default: 15)
    tagMinScore: 0.1f,                        // Optional: min score (default: 0.1)
    marketingLimit: null,                     // Optional
    marketingMinScore: 0.3f,                  // Optional (default: 0.3)
    includeInSim: true,                       // Optional (default: true)
    articleUrl: "https://example.com"         // Optional
);

Get Similar Articles

var articles = await client.GetSimilarAsync(
    documentId: "doc123",                     // Required
    maxRows: 10,                              // Optional: limit results
    pastDays: 30,                             // Optional: limit by date
    publicationIds: new[] { "pub1", "pub2" }  // Optional: filter by publication
);

Update Article

var article = await client.UpdateArticleAsync(
    documentId: "doc123",                     // Required
    published: new DateTime(2024, 1, 15),     // Optional
    headline: "Updated Headline",             // Optional
    writer: "Author Name",                    // Optional
    category: "News",                         // Optional
    content: "Updated content",               // Optional
    summary: "Summary",                       // Optional
    publicationId: "pub1",                    // Optional
    articleUrl: "https://example.com",        // Optional
    includeInSim: true                        // Optional
);

Train AI Topics

var trainingTags = await client.TrainAiTopicsAsync(
    documentId: "doc123",                     // Required
    tags: new[] { "tag1", "tag2", "tag3" }    // Required
);

EDGE API

Get AI Topics (Single URL)

var response = await client.GetAiTopicsAsync(
    url: "https://example.com/article",       // Required
    origin: "https://yoursite.com"            // Optional: override default origin
);

Get AI Topics with Auto-Retry

var response = await client.GetAiTopicsWaitAsync(
    url: "https://example.com/article",       // Required
    origin: "https://yoursite.com",           // Optional
    maxRetries: 10,                           // Optional (default: 10)
    retryInterval: 6,                         // Optional (default: 6s)
    initialDelay: 2                           // Optional (default: 2s)
);

Raw Response Methods

All methods have *Raw variants that return the raw HttpResponseMessage object:

// REST
var rawResponse = await client.GetAiTopicsRawAsync(content: "Text");
Console.WriteLine(rawResponse.StatusCode);
Console.WriteLine(await rawResponse.Content.ReadAsStringAsync());

// EDGE
var rawResponse = await client.GetAiTopicsRawAsync(url: "https://example.com");
var json = await rawResponse.Content.ReadAsStringAsync();
Console.WriteLine(json);

Error Handling

The SDK provides specific exceptions for different error scenarios:

using Neuwo.Api.Clients;
using Neuwo.Api.Configuration;
using Neuwo.Api.Exceptions;

var options = new NeuwoRestClientOptions
{
    Token = "your-token",
    BaseUrl = "https://custom.api.com"
};

using var client = new NeuwoRestClient(options);

try
{
    var response = await client.GetAiTopicsAsync(content: "Your content here");
}
catch (ValidationException ex)
{
    Console.WriteLine($"Invalid input: {ex.Message}");
    Console.WriteLine($"Validation details: {ex.ValidationDetails}");
}
catch (AuthenticationException ex)
{
    Console.WriteLine($"Authentication failed: {ex.Message}");
}
catch (NoDataAvailableException ex)
{
    Console.WriteLine($"Data not yet available: {ex.Message}");
}
catch (ContentNotAvailableException ex)
{
    Console.WriteLine($"Content could not be analysed: {ex.Message}");
}
catch (NetworkException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
}
catch (NeuwoApiException ex)
{
    Console.WriteLine($"API error: {ex.Message}");
    Console.WriteLine($"Status code: {ex.StatusCode}");
}

Exception Hierarchy

Logging

The SDK integrates with Microsoft.Extensions.Logging for comprehensive logging support. You can provide a logger instance to see detailed API communication:

using Microsoft.Extensions.Logging;
using Neuwo.Api.Clients;
using Neuwo.Api.Configuration;

// Create logger factory
using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddConsole()
        .SetMinimumLevel(LogLevel.Debug);
});

var logger = loggerFactory.CreateLogger<NeuwoRestClient>();

// Pass logger to client
var options = new NeuwoRestClientOptions
{
    Token = "your-token",
    BaseUrl = "https://custom.api.com",
    Logger = logger
};

using var client = new NeuwoRestClient(options);

Available log levels:

Note: Sensitive information like tokens are automatically sanitized in log output.