Upgrading

FreeAgent.NET follows Semantic Versioning. Until MVP completion, all releases are prerelease (0.x.y-alpha.n).

Prerelease expectations

Public APIs may change between alpha releases.
Pin an exact version in your project file:

<PackageReference Include="FreeAgent.Client" Version="0.1.0-alpha.4" />

Upgrade checklist

Read the GitHub Release notes for breaking changes.
Update the package reference and restore.
Run your test suite - model mapping changes (for example string to enum, DateTime to DateOnly) are the most common breaks during alpha.
Check API coverage for newly implemented endpoints.

Recent breaking changes (alpha)

List API naming (Stripe.NET parity)

Collection reads now use Stripe.NET-aligned names on resource services:

Before	After
`GetContactsPageAsync`	`client.Contacts.ListAsync`
`GetAllContactsAsync`	`client.Contacts.ListAutoPagingAsync`
`GetProjectsPageAsync`	`client.Projects.ListAsync`
`GetAllProjectsAsync`	`client.Projects.ListAutoPagingAsync`
`GetUsersAsync`	`client.Users.ListAsync`
`GetCategoriesAsync`	`client.Categories.ListAsync`
`GetEmailAddressesAsync`	`client.EmailAddresses.ListAsync`
`GetBusinessCategoriesAsync`	`client.Company.ListBusinessCategoriesAsync`
`GetTaxTimelineAsync`	`client.Company.ListTaxTimelineAsync`

Single-resource reads (GetContactAsync, GetProjectAsync, etc.) are unchanged.

Linked resource fields on Projects

Project.Contact is now Contact? (read) for nested or hydrated billing contact data. Set ContactId when creating or updating a project.

Use GetProjectAsync(id, new ProjectGetOptions { IncludeContact = true }) when you need full contact fields such as OrganisationName. Use ContactName when a display label from a single HTTP call is enough.

On update, the SDK round-trips ContactId from the read model. Linked resource writes across the SDK use *Id on models (and CategoryNominalCode for categories), not *Reference properties or client.Urls at the call site.

Project list methods accept ContactReference? contact and long? contactId instead of string? contact. Supply only one contact filter parameter - specifying both throws ArgumentException.

Use TryGetResourceId() or GetResourceId() when a parsed identifier is required. ResourceId returns 0 when parsing fails.

Top-level resources implement IFreeAgentResource with a computed ResourceId property. Use project.ResourceId for display, or the extension methods when calling services.

ExpandableField<T> is no longer part of the public API.

Project task naming consistency

Task-related public API members now use the ProjectTask prefix to align with the ProjectTask model and avoid confusion with System.Threading.Tasks.Task:

Before	After
`client.Tasks`	`client.ProjectTasks`
`TaskService`	`ProjectTaskService`
`GetTaskAsync` / `CreateTaskAsync` / `UpdateTaskAsync` / `DeleteTaskAsync`	`GetProjectTaskAsync` / `CreateProjectTaskAsync` / `UpdateProjectTaskAsync` / `DeleteProjectTaskAsync`
`TaskGetOptions`	`ProjectTaskGetOptions`
`TaskReference`	`ProjectTaskReference`
`client.Urls.Task(id)`	`client.Urls.ProjectTask(id)`
`TaskStatus`, `TaskViews`, `TaskSortOptions`, `TaskBillingPeriod`	`ProjectTaskStatus`, `ProjectTaskViews`, `ProjectTaskSortOptions`, `ProjectTaskBillingPeriod`
`Timeslip.Task` / `Timeslip.TaskId`	`Timeslip.ProjectTask` / `Timeslip.ProjectTaskId`
`TimeslipGetOptions.IncludeTask`	`TimeslipGetOptions.IncludeProjectTask`

Wire JSON property names (task, tasks) are unchanged.

Contacts list returns full `Contact` models

Contact list methods now return Contact instead of the removed ContactSummary type. Update any code that depended on the slimmer list shape.

When creating or updating contacts, read-only API fields (url, balances, mandate state, timestamps) are ignored during serialisation. You can still round-trip a Contact retrieved from the API without sending those fields back.

Stable releases

Stable 1.0.0 will follow the criteria in VERSIONING.md. Until then, treat every upgrade as potentially breaking.