Endjin.FreeAgent.Client.Extensions 1.0.0-preview.2

Endjin.FreeAgent.Client.Extensions

Extension methods and additional functionality for the Endjin.FreeAgent.Client library, providing enhanced features for working with the FreeAgent API.

Features

• Extension Members - .NET 10 extension member support for FreeAgent client
• Timesheets Module - Comprehensive timesheet management and aggregation
• Project Extensions - Advanced project filtering and management
• User Settings - User preference and settings management
• Activity Summaries - Time tracking and activity reporting
• Flexible Architecture - Extensible registry pattern for adding custom modules

Installation

Install via NuGet Package Manager:

dotnet add package Endjin.FreeAgent.Client.Extensions

Or via Package Manager Console:

Install-Package Endjin.FreeAgent.Client.Extensions

Quick Start

Timesheets Extension

The Timesheets extension provides comprehensive time tracking functionality:

using Endjin.FreeAgent.Client;
using Endjin.FreeAgent.Client.Extensions;
using Microsoft.Extensions.Caching.Memory;

// Initialize client with Timesheets extension
FreeAgentClient client = FreeAgentClient.CreateWithTimesheets(
    options,
    cache,
    httpClientFactory,
    loggerFactory);

// Or add to existing client
client.WithTimesheets(cache);

// Access timesheet functionality
IEnumerable<WeeklyTimesheet> weeklyTimesheets = await client.Timesheets.GetWeeklyTimesheetsAsync(
    DateOnly.FromDateTime(DateTime.Now.AddDays(-30)),
    DateOnly.FromDateTime(DateTime.Now));

// Get monthly summary
MonthlyTimesheet monthlyTimesheet = await client.Timesheets.GetMonthlyTimesheetAsync(
    DateTime.Now.Year,
    DateTime.Now.Month);

Project Extensions

Advanced project filtering and management:

using Endjin.FreeAgent.Client.Extensions;

// Configure project filtering
ProjectFilterOptions filterOptions = new()
{
    ExcludePreProjects = true,
    RequireContactEntry = true,
    RequireOrganizationName = true,
    ExcludeEndjinProjectsByDefault = true,
    IncludedEndjinProjectIds = new HashSet<string> { "123", "456" },
    ExcludedProjectIds = new HashSet<string> { "789" }
};

// Get filtered active projects
IEnumerable<Project> filteredProjects = await client.Projects.GetIncludedActiveAsync(filterOptions);

// Get project details with time tracking
Dictionary<Project, List<(string Customer, string Project, string User, DateTimeOffset Date,
    int Year, int WeekNumber, decimal Effort, decimal? DayRate, decimal? HourlyRate,
    string Level, decimal? Cost, string Comment)>> projectDetails =
    await client.Projects.GetActiveProjectsDetailsByDateRangeAsync(dateRange);

User Settings

Manage user preferences and settings:

using Endjin.FreeAgent.Client.Extensions;

// Initialize user settings service
UserSettingsService settingsService = new(cache);

// Get user settings
UserSettings? settings = await settingsService.GetUserSettingsAsync("user123");

// Update settings
UserSettings newSettings = new()
{
    UserId = "user123",
    DefaultProjectId = "project456",
    DefaultTaskId = "task789",
    PreferredTimeFormat = "24h",
    WeekStartDay = DayOfWeek.Monday
};

await settingsService.SaveUserSettingsAsync(newSettings);

Extension Registry

The extension registry pattern allows for modular functionality:

// Check if extensions are available
if (client.HasTimesheets)
{
    Timesheets timesheets = client.Timesheets;
    // Use timesheet functionality
}

// Register custom extensions
ExtensionRegistry registry = new();
registry.Register("CustomModule", new CustomModule());

// Access registered extensions
CustomModule? custom = registry.Get<CustomModule>("CustomModule");

Advanced Features

Activity Summaries

Aggregate time tracking data:

// Get user activity summary
UserActivitySummary summary = await client.Timesheets.GetUserActivitySummaryAsync(
    "user123",
    DateOnly.FromDateTime(DateTime.Now.AddMonths(-1)),
    DateOnly.FromDateTime(DateTime.Now));

// Get project summaries
ProjectsSummary projectsSummary = await client.Projects.GetProjectsSummaryAsync(dateRange);

Weekly and Monthly Aggregations

// Weekly timesheets with detailed entries
IEnumerable<WeeklyTimesheet> weeklyData = await client.Timesheets.GetWeeklyTimesheetsAsync(
    startDate,
    endDate);

foreach (WeeklyTimesheet week in weeklyData)
{
    Console.WriteLine($"Week {week.WeekNumber}: {week.TotalHours} hours");
    foreach (TimeSheetActivityEntry entry in week.Entries)
    {
        Console.WriteLine($"  {entry.ProjectName}: {entry.Hours}h");
    }
}

// Monthly aggregation
MonthlyTimesheet monthly = await client.Timesheets.GetMonthlyTimesheetAsync(2024, 9);
Console.WriteLine($"September 2024: {monthly.TotalHours} hours, {monthly.BillableHours} billable");

Filtering and Queries

// Complex project queries
IEnumerable<Project> projects = await client.Projects.GetIncludedActiveAsync(
    new ProjectFilterOptions
    {
        ExcludePreProjects = true,
        RequireContactEntry = true,
        MinimumBudget = 10000m,
        Currency = "GBP",
        Status = "Active"
    });

// Time-based filtering
IEnumerable<Timeslip> recentWork = await client.Timesheets.GetTimeslipsByDateRangeAsync(
    DateOnly.FromDateTime(DateTime.Now.AddDays(-7)),
    DateOnly.FromDateTime(DateTime.Now),
    userId: "user123",
    projectId: "project456");

Extension Members (C# 14)

This library leverages .NET 10's extension members feature for cleaner API design:

// Extension members provide direct access to extended functionality
client.Timesheets.GetWeeklyTimesheetsAsync(...);  // Direct member access
client.Projects.GetIncludedActiveAsync(...);       // Enhanced project methods

Requirements

• .NET 10.0 or later
• Endjin.FreeAgent.Client 1.0.0-preview.1 or later
• Endjin.FreeAgent.Domain 1.0.0-preview.1 or later

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For support, please contact Endjin Limited or raise an issue on our GitHub repository.

Copyright (c) Endjin Limited. All rights reserved.