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

Endjin.FreeAgent.Domain.Extensions

Extension types and helper methods for the Endjin.FreeAgent.Domain library, providing additional domain models and utilities for enhanced FreeAgent API interactions.

Features

• Extended Domain Models - Additional types for timesheet management and reporting
• Date/Time Extensions - Helper methods for working with dates and fiscal periods
• Currency Extensions - Decimal formatting and currency handling utilities
• Timesheet Models - Weekly, monthly, and yearly timesheet aggregations
• User Settings - Domain models for user preferences and configuration
• Project Summaries - Enhanced project reporting models

Installation

Install via NuGet Package Manager:

dotnet add package Endjin.FreeAgent.Domain.Extensions

Or via Package Manager Console:

Install-Package Endjin.FreeAgent.Domain.Extensions

Domain Models

Timesheet Models

Comprehensive timesheet domain models for various time periods:

using Endjin.FreeAgent.Domain.Extensions;

// Weekly timesheet with entries
WeeklyTimesheet weeklyTimesheet = new()
{
    WeekNumber = 42,
    Year = 2024,
    StartDate = new DateOnly(2024, 10, 14),
    EndDate = new DateOnly(2024, 10, 20),
    TotalHours = 40.0m,
    BillableHours = 35.0m,
    Entries = ImmutableList.Create(
        new TimeSheetActivityEntry
        {
            ProjectName = "Client Project A",
            TaskName = "Development",
            Hours = 20.0m,
            IsBillable = true
        }
    )
};

// Monthly aggregation
MonthlyTimesheet monthlyTimesheet = new()
{
    Year = 2024,
    Month = 10,
    MonthName = "October",
    TotalHours = 160.0m,
    BillableHours = 140.0m,
    NonBillableHours = 20.0m,
    WeeklyTimesheets = ImmutableList.Create(weeklyTimesheet)
};

// Yearly overview
YearlyTimesheet yearlyTimesheet = new()
{
    Year = 2024,
    TotalHours = 1920.0m,
    BillableHours = 1680.0m,
    MonthlyTimesheets = ImmutableList.Create(monthlyTimesheet)
};

User Settings

Domain model for user preferences:

using Endjin.FreeAgent.Domain.Extensions;

UserSettings settings = new()
{
    UserId = "user123",
    DefaultProjectId = "project456",
    DefaultTaskId = "task789",
    PreferredTimeFormat = "24h",
    WeekStartDay = DayOfWeek.Monday,
    DefaultBillingRate = 150.0m,
    Currency = "GBP"
};

// User summary with statistics
UserSummary summary = new()
{
    UserId = "user123",
    DisplayName = "John Smith",
    Email = "john.smith@example.com",
    TotalHoursThisWeek = 40.0m,
    TotalHoursThisMonth = 160.0m,
    UtilizationRate = 87.5m
};

Project Models

Enhanced project reporting models:

using Endjin.FreeAgent.Domain.Extensions;

// Project summary
ProjectSummary projectSummary = new()
{
    ProjectId = "project123",
    ProjectName = "Website Development",
    ClientName = "Acme Corp",
    TotalHours = 240.0m,
    BudgetHours = 300.0m,
    BudgetUtilization = 80.0m,
    TotalRevenue = 36000.0m
};

// Detailed project information
ProjectDetail projectDetail = new()
{
    Project = projectSummary,
    Activities = ImmutableList.Create(
        new TimeSheetActivity
        {
            TaskName = "Frontend Development",
            TotalHours = 120.0m,
            BillingRate = 150.0m
        },
        new TimeSheetActivity
        {
            TaskName = "Backend Development",
            TotalHours = 120.0m,
            BillingRate = 150.0m
        }
    )
};

Extension Methods

DateTime Extensions

Helper methods for working with dates and fiscal periods:

using Endjin.FreeAgent.Domain.Extensions;
using NodaTime;

// Get week number
int weekNumber = DateTime.Now.GetIsoWeekNumber();

// Get fiscal year
int fiscalYear = DateTime.Now.GetFiscalYear(fiscalYearStartMonth: 4);

// Get month range
(DateOnly start, DateOnly end) = DateTimeExtensions.GetMonthRange(2024, 10);

// Get week range
(DateOnly start, DateOnly end) = DateTimeExtensions.GetWeekRange(2024, 42);

// Convert to FreeAgent date format
string dateString = DateOnly.Today.ToFreeAgentDateString();

// Parse FreeAgent date
DateOnly date = DateTimeExtensions.ParseFreeAgentDate("2024-10-20");

Currency Extensions

Decimal formatting and currency utilities:

using Endjin.FreeAgent.Domain.Extensions;

// Format as currency
decimal amount = 1234.56m;
string formatted = amount.ToCurrencyString("GBP"); // "£1,234.56"

// Round to currency precision
decimal rounded = amount.RoundToCurrency(); // 1234.56

// Calculate VAT
decimal net = 100.0m;
decimal vatRate = 20.0m;
decimal gross = net.AddVat(vatRate); // 120.00
decimal vatAmount = net.CalculateVat(vatRate); // 20.00

Repository Pattern

User settings repository for data persistence:

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

// Initialize repository
IMemoryCache cache = new MemoryCache(new MemoryCacheOptions());
UserSettingsRepository repository = new(cache);

// Save settings
UserSettings settings = new() { UserId = "user123", /* ... */ };
await repository.SaveAsync(settings);

// Retrieve settings
UserSettings? retrieved = await repository.GetAsync("user123");

// Delete settings
await repository.DeleteAsync("user123");

// Get all settings
IEnumerable<UserSettings> all = await repository.GetAllAsync();

Time Period Models

Working with fiscal periods:

// Week model
Week week = new()
{
    WeekNumber = 42,
    Year = 2024,
    StartDate = new DateOnly(2024, 10, 14),
    EndDate = new DateOnly(2024, 10, 20)
};

// Month model
Month month = new()
{
    MonthNumber = 10,
    Year = 2024,
    Name = "October",
    TotalDays = 31
};

// Custom timesheet periods
Timesheet customPeriod = new()
{
    StartDate = DateOnly.Today.AddDays(-30),
    EndDate = DateOnly.Today,
    Description = "Last 30 Days"
};

Employment Roles

Domain model for employment types:

EmploymentRole role = new()
{
    RoleId = "role123",
    Title = "Senior Developer",
    Department = "Engineering",
    Level = "Senior",
    DefaultBillingRate = 150.0m
};

Requirements

• .NET 10.0 or later
• Endjin.FreeAgent.Domain 1.0.0-preview.1 or later
• NodaTime 3.2.2 or later
• System.Collections.Immutable

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.