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:

Exception	HTTP Status
APIBadRequestException	400
APIForbiddenException	403
APINotFoundException	404
APITooManyRequestsException	429
APIServiceUnavailableException	503

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

Available resources

Resource	Property	Operations
Entries	client.Entries	Get, Create, Edit, Delete, Approve, Unapprove, Mark Invoiced
Projects	client.Projects	Get, Create, Edit, Delete, Archive, Unarchive, Merge
Tags	client.Tags	Get, Create, Edit, Delete, Merge
Users	client.Users	Get, Create, Edit, Delete, Activate, Deactivate, Project Access
Current User	client.CurrentUser	Get, Edit
Teams	client.Teams	Get, Create, Edit, Delete, Manage Users
Timers	client.Timers	Get, Create, Edit, Delete, Start, Pause, Log
Invoices	client.Invoices	Get, Create, Edit, Delete, Mark Paid/Unpaid, Manage Entries/Expenses
Expenses	client.Expenses	Get, Create, Edit, Delete
Inbox Entries	client.InboxEntries	Get, Log, Discard
Project Groups	client.ProjectGroups	Get, Create, Edit, Delete, Manage Projects
Webhooks	client.Webhooks	Get, Create, Edit, Delete, Enable, Disable, Manage Events
Broadcast Receivers	client.BroadcastReceivers	Get, Create, Edit, Delete, Enable, Disable, Manage Subjects
Account	client.Account	Get

Links

• Noko API documentation
• NuGet package

License

MIT