Lolzteam.Api 0.3.0

Lolzteam.Api

Production-grade C# client for the Lolzteam Forum and Market APIs.

• Code-generated from official OpenAPI schemas — 151 Forum and 115 Market operations, all strongly typed
• AOT-safe deserialization — each response record reads itself directly from a binary stream, zero runtime reflection
• Low allocation HTTP — ArrayPool<byte> response buffering with a static pooled HttpMessageHandler
• Automatic retry on 429 / 502 / 503 with Retry-After header respect and configurable back-off
• Client-side rate limiting — proactively throttles requests before the server ever returns 429
• Proxy support — HTTP, HTTPS, and SOCKS5 with optional per-proxy credentials
• Multi-target — netstandard2.0, netstandard2.1, net6.0, net8.0 (.NET Framework 4.6.1+, Unity, Xamarin)
• Optional DI package — IHttpClientFactory integration for ASP.NET Core / Generic Host
• Well tested — 80%+ line coverage across all handwritten code (generated types excluded)

Table of Contents

• Installation
• Getting Started
• Configuration
• Retry
• Rate Limiting
• Proxy
• Dependency Injection
• Error Handling
• Forum API Groups
• Market API Groups
• Regenerating Code
• License

Installation

Install the core package from NuGet:

dotnet add package Lolzteam.Api

For ASP.NET Core / Generic Host with IHttpClientFactory, also install the optional DI package:

dotnet add package Lolzteam.Api.DependencyInjection

Getting Started

Create a ClientConfig with your bearer token and instantiate a client:

using Lolzteam.Api.Generated.Forum;
using Lolzteam.Api.Runtime;

var config = new ClientConfig
{
    Token   = "your-bearer-token",
    BaseUrl = "https://prod-api.lolz.live",
};

using var forum = new ForumClient(config);

var thread = await forum.Threads.GetAsync(12345);
Console.WriteLine(thread.Thread.ThreadTitle);

var list = await forum.Threads.ListAsync(new() { ForumId = 7 });
foreach (var t in list.Threads)
    Console.WriteLine($"{t.ThreadId}: {t.ThreadTitle}");

Market client works the same way:

using Lolzteam.Api.Runtime;
using Lolzteam.Api.Generated.Market;

using var market = new MarketClient(new ClientConfig
{
    Token   = "your-bearer-token",
    BaseUrl = "https://prod-api.lzt.market",
});

// Browse account listings
var listing = await market.List.UserAsync(new() { CategoryId = CategoryId.V10, Page = 1 });

Both clients implement IDisposable. using or using var is recommended when lifetime is scoped; for singleton use omit the using.

Configuration

ClientConfig is an immutable C# record. All properties except Token are optional.

using Lolzteam.Api.Runtime;

var config = new ClientConfig
{
    // Required
    Token = "your-bearer-token",

    // Override base URL (defaults to the official endpoint per client)
    BaseUrl = "https://prod-api.lolz.live",

    // Proxy (HTTP, HTTPS, or SOCKS5)
    Proxy = new ProxyConfig("socks5://user:pass@proxy.example.com:1080"),

    // Retry policy (default: 3 retries, 500 ms base, 30 s max)
    Retry = new RetryConfig
    {
        MaxRetries = 5,
        BaseDelay  = TimeSpan.FromMilliseconds(300),
        MaxDelay   = TimeSpan.FromSeconds(60),
    },

    // Client-side rate limiting (per-minute budget)
    RateLimit       = new RateLimitConfig(RequestsPerMinute: 300),
    SearchRateLimit = new RateLimitConfig(RequestsPerMinute: 20),

    // Per-request timeout
    Timeout = TimeSpan.FromSeconds(30),

    // Callback invoked before each retry attempt (for logging, metrics, etc.)
    OnRetry = ctx => Console.WriteLine($"Retry — {ctx.Exception.Message}"),
};

Retry

The default policy retries on 429 Too Many Requests, 502 Bad Gateway, and 503 Service Unavailable. On 429 the Retry-After response header is respected; on 5xx a configurable exponential back-off with jitter is used.

// Disable retries entirely
var config = new ClientConfig { Token = "...", Retry = null };

// Custom policy
var config = new ClientConfig
{
    Token = "...",
    Retry = new RetryConfig
    {
        MaxRetries = 3,
        BaseDelay  = TimeSpan.FromMilliseconds(500),
        MaxDelay   = TimeSpan.FromSeconds(30),
    },
    OnRetry = ctx => logger.LogWarning("Retry {Attempt} after {Delay:g}: {Message}", ctx.Attempt, ctx.Delay, ctx.Exception.Message),
};

When all retries are exhausted a RetryExhaustedException is thrown, with the last underlying exception as InnerException.

Rate Limiting

Client-side rate limiting is disabled by default. When configured, a sliding-window token bucket ensures the request rate never exceeds the specified budget, preventing the server from returning 429 in the first place.

var config = new ClientConfig
{
    Token = "...",

    // General-purpose endpoints: 300 req/min (Forum default)
    RateLimit = new RateLimitConfig(300),

    // Search endpoints are counted separately (stricter limit)
    SearchRateLimit = new RateLimitConfig(20),
};

Search requests are automatically identified by the client and consume the SearchRateLimit bucket when set.

Proxy

Pass a ProxyConfig with a URI. Supported schemes: http://, https://, socks5://. Credentials are embedded in the URI.

// HTTP proxy, no auth
Proxy = new ProxyConfig("http://proxy.example.com:8080")

// SOCKS5 proxy with credentials
Proxy = new ProxyConfig("socks5://user:secret@10.0.0.1:1080")

Handlers are cached per proxy URL at the process level, so creating multiple clients with the same proxy reuses the underlying socket pool.

Dependency Injection

Install Lolzteam.Api.DependencyInjection and call AddLolzteamClient<TClient> in your Program.cs. This registers a named HttpClient via IHttpClientFactory for proper socket lifecycle management in hosted applications.

You can configure the client either with a pre-built ClientConfig:

// Program.cs
builder.Services.AddLolzteamClient<ForumClient>(new ClientConfig
{
    Token   = builder.Configuration["Lolzteam:Token"]!,
    Retry   = new RetryConfig { MaxRetries = 3 },
});

Or with the fluent builder, which is more convenient when reading values from configuration:

builder.Services.AddLolzteamClient<ForumClient>(b => b
    .WithToken(builder.Configuration["Lolzteam:Token"]!)
    .WithProxy("socks5://proxy:1080")
    .WithRateLimit(300)
    .WithTimeout(TimeSpan.FromSeconds(60))
);

Resolve the client in your services via constructor injection:

public class ThreadService(ForumClient forum)
{
    public Task<ThreadsResponse> GetLatestAsync()
        => forum.Threads.ListAsync(new() { ForumId = 7 });
}

When using IHttpClientFactory the HttpClient lifetime is managed by the factory. Do not dispose the injected client in this case.

Error Handling

All client-facing exceptions derive from LolzteamException.

try
{
    var thread = await forum.Threads.GetAsync(12345);
}
catch (RateLimitException ex)
{
    // Honour the server's hint even when client-side limiting is enabled
    await Task.Delay(ex.RetryAfter ?? TimeSpan.FromSeconds(5));
}
catch (HttpApiException ex) when (ex.StatusCode == 404)
{
    Console.WriteLine("Thread not found.");
}
catch (ServerException ex)
{
    Console.WriteLine($"Server error {ex.StatusCode}: {ex.ResponseBody}");
}

Forum API Groups

ForumClient exposes 151 operations across 18 endpoint groups:

Market API Groups

MarketClient exposes 115 operations across 14 endpoint groups:

Regenerating Code

The clients in src/Lolzteam.Api/Generated/ are produced from the OpenAPI schemas in schemas/. To regenerate after updating a schema, run:

dotnet run --project codegen/Lolzteam.Codegen

The generator will:

1. Parse schemas/forum.json and schemas/market.json
2. Delete existing .cs files in each Generated/ subdirectory and its Types/ sub-directory
3. Emit per-type files into Generated/<Api>/Types/<Class>.cs (enums, schemas, and per-group input DTOs as separate files)
4. Emit ForumClient.cs / MarketClient.cs and IForumClient.cs / IMarketClient.cs

Splitting types across multiple files keeps IDE analysers responsive on large schemas. Generated files are committed to the repository so the library builds without running the codegen.

License

This library is licensed under the MIT License.