Noko.Net 1.0.0

Noko.Net

A .NET client library for the Noko time-tracking API (v2).

Installation

dotnet add package Noko.Net

Quick start

using NokoAPI;

// Create a client with your personal access token
var client = new NokoClient(
    new UserAgent("MyApp", "1.0"),
    "your-personal-access-token");

// Create a time entry
var entry = await client.Entries.CreateAsync(new CreateEntryRequest
{
    Date = DateOnly.FromDateTime(DateTime.Today),
    Minutes = 60,
    ProjectId = 123,
    Description = "Implemented feature #45"
});

// List recent entries with filters
var entries = await client.Entries.GetAsync(new GetEntriesRequest
{
    FromDate = DateOnly.FromDateTime(DateTime.Today.AddDays(-7)),
    Billable = true
});

// Paginate through all results
var page = await client.Tags.GetAsync(new GetTagsRequest());
while (true)
{
    foreach (var tag in page)
        Console.WriteLine($"{tag.Id}: {tag.Name}");

    var next = await client.GetNextPageAsync(page);
    if (next == null) break;
    page = next;
}

Authentication

Noko uses personal access tokens for authentication. Generate one from your Noko account and pass it when creating the client.

// Simple constructor
var client = new NokoClient(new UserAgent("MyApp", "1.0"), "your-token");

// Or via config for more control
var config = NokoClientConfig.BuildDefault(new UserAgent("MyApp", "1.0"))
    .WithPersonalAccessToken("your-token")
    .WithTimeout(TimeSpan.FromSeconds(30));
var client = new NokoClient(config);

Configuration

NokoClientConfig provides fluent setters for customizing client behavior:

var config = NokoClientConfig.BuildDefault(new UserAgent("MyApp", "1.0"), "your-token")
    .WithTimeout(TimeSpan.FromSeconds(30))           // Custom request timeout
    .WithHttpMessageHandler(myPollyHandler)           // Polly, logging, or mock handler
    .WithBaseAddress(new Uri("https://custom.url/"))  // Custom API base URL
    .WithJsonSerializerOptions(myOptions);             // Custom JSON serialization

IHttpClientFactory integration

For production services using dependency injection, you can supply your own HttpClient:

// In Startup / Program.cs
services.AddHttpClient("Noko", client =>
{
    client.BaseAddress = new Uri("https://api.nokotime.com/v2/");
    client.DefaultRequestHeaders.Add("X-NokoToken", token);
    client.DefaultRequestHeaders.UserAgent.Add(
        new UserAgent("MyApp", "1.0").CreateHeader());
});

// In your service
var httpClient = httpClientFactory.CreateClient("Noko");
var config = NokoClientConfig.BuildDefault(new UserAgent("MyApp", "1.0"))
    .WithHttpClient(httpClient);
var client = new NokoClient(config);

The library never disposes a caller-supplied HttpClient.

Pagination

List endpoints return Paginated<T>, which wraps List<T> and exposes First, Next, Previous, and Last link properties. Use the helper methods on INokoClient to navigate:

var page = await client.Entries.GetAsync(new GetEntriesRequest());

var next = await client.GetNextPageAsync(page);       // null if no next page
var prev = await client.GetPreviousPageAsync(page);   // null if no previous page
var first = await client.GetFirstPageAsync(page);
var last = await client.GetLastPageAsync(page);

Error handling

The library throws typed exceptions for HTTP errors:

APITooManyRequestsException includes a RetryAfter property with the server-suggested wait duration.

Available resources

Links

• Noko API documentation
• NuGet package

License

MIT