LANCommander.HQ.SDK 1.1.2

LANCommander.HQ.SDK

.NET client SDK for the LANCommander.HQ API.

LANCommander.HQ is a community-driven metadata service for LAN games. This SDK gives .NET applications strongly-typed access to every endpoint exposed by the API: game metadata search across providers (IGDB, MobyGames, Steam, GOG, etc.), admin CRUD for the canonical catalog, taxonomies, edition groups, identity mappings, DMCA workflow, and master-server browsing.

Install

dotnet add package LANCommander.HQ.SDK

Quick start

using LANCommander.HQ.SDK;
using LANCommander.HQ.SDK.Authentication;

// A long-running service: authenticate once, stay authenticated.
using var client = new HQClient(new HQClientOptions
{
    BaseAddress = new Uri("https://api.lancommander.app"),
    RefreshToken = configuration["HQ:RefreshToken"],
    TokenStore = new FileTokenStore("/var/lib/myapp/hq-tokens.json"),
    ClientName = "my-lancommander-server",
});

var providers = await client.Providers.ListAsync();
var search = await client.Games.SearchAsync(provider: "igdb", query: "Half-Life");
var game = await client.Games.GetAsync("igdb", search.First().ProviderId);

Dependency injection

using LANCommander.HQ.SDK.Extensions;

services.AddLANCommanderHQ(options =>
{
    options.BaseAddress = new Uri(configuration["HQ:BaseAddress"]!);
    options.RefreshToken = configuration["HQ:RefreshToken"];
    options.TokenStore = new FileTokenStore(configuration["HQ:TokenPath"]!);
});

Then inject HQClient (or any of the per-resource services like AdminGamesClient, MasterServersClient, etc.) anywhere in your app.

Authentication

The SDK sends a short-lived access token as an Authorization: Bearer header, and renews it from a long-lived refresh token before it expires. Set a refresh token once and the client stays authenticated indefinitely — including across restarts, and across long idle periods where nothing calls the API at all.

Getting the first token pair

Access tokens cannot be minted from nothing, so one interactive sign-in is needed to start a connection:

1. Send the user to GET /Auth/Login?returnUrl={yourCallback} on the API server.
2. After they sign in, GET /Auth/TokenRelay redirects to your callback with a single-use ?code= parameter, valid for one minute.
3. Exchange it, and persist the result:

var pair = await client.Auth.ExchangeCodeAsync(code, clientName: "my-server");
await tokenStore.SaveAsync(pair!.ToTokenSet());

An already-signed-in caller can skip the browser entirely and open a connection directly with client.Auth.CreateSessionAsync("my-server").

Rotation, and why the store matters

Refresh tokens are single-use. Every renewal returns a new refresh token and invalidates the previous one, so the SDK writes each new token set to IHQTokenStore before using it.

This makes the store load-bearing rather than an optimisation. The default InMemoryTokenStore loses the rotated token when the process exits, which means re-authenticating on every start. Any service should use FileTokenStore — or its own IHQTokenStore over a secret manager, which is the better option on a host where other tenants can read the filesystem.

Two important consequences:

• One client per credential. Two processes sharing a refresh token will rotate against each other. The server treats a second presentation of a spent token as theft and revokes the whole session, signing both of them out. Give each instance its own connection.
• Rejection is terminal. If the refresh token is revoked, expires from inactivity, or is flagged as reused, the SDK clears the store and throws HQAuthenticationException. Retrying will not help; the connection must be set up again.

Refresh tokens expire on inactivity, not on a fixed schedule — the clock resets on every use — so a client that calls even occasionally never needs re-authorising. Users can see and revoke connections from their account page, which is what ClientName labels.

Other credential options

A Locale option (or X-Locale header) is forwarded so server-side localization picks the right translation.

Coverage

License

MIT