API v1 Migration - Phase 3: Final release preperation and refactoring

[AhmedZaki99]

This PR is the final API-v1 migration pass for Todoist.Net and supersedes the original “docs-only” scope planned for Phase 3. (a part of the plan discussed in #70)

Summary

Phase 3 evolved into a full contract and architecture finalization pass to align the library with the current unified Todoist API v1 surface.

Compared to the original plan, this PR does significantly more than documentation updates:

• restructures models/services by domain,
• redesigns core contracts and sync/command primitives,
• adds v1 endpoint coverage for additional domains (workspaces, workspace filters, view options, calendars, IDs),
• and finalizes TodoistClient + REST behavior around the redesigned service model.

Why this change expanded

While validating migration completeness, we found that the initial Phase 1/2 work still left structural gaps for:

• newly available v1 domains and payload shapes,
• consistent request/response/command modeling,
• and maintainable client/service contracts for long-term API evolution.

This PR closes those gaps before release rather than shipping partial abstractions and revisiting them in follow-up breaking releases.

Scope of change

1) Structure and organization baseline (commit: 6fc69e6)

• Reorganized Models and Services into domain folders (e.g., Tasks, Projects, Activity, Commands, Common, ...).
• Updated affected references/usings and normalized several argument types (ReorderEntry usage alignment, etc.).
• Removed obsolete model artifacts (IdsArgument) and cleaned project includes.

2) Common model + sync/command redesign (commit: 5bbd02e)

• Added ThrowHelper for centralized guard clauses.
• Refactored TodoistException into v1-oriented error metadata usage.
• Introduced/reworked core abstractions:
  • command operation/result body model,
  • new sync response model family under Models/Sync,
  • shared pagination/search query base types,
  • common enum/file/user summary primitives.
• Removed/replaced legacy common sync resource wrappers that no longer fit the redesigned contracts.

3) Domain model redesign for v1 request/response parity (commit: d03ac70)

• Refactored major domain entities and query models across Activity, Comments, Filters, Labels, Notifications, Projects, Reminders, Sections, Sharing, Tasks, and Users.
• Added explicit pagination/query/request argument models where v1 endpoints require them.
• Introduced richer domain structures (project access/collaborator models, user stats/settings/limits, notification setting update payloads, etc.).
• Replaced/removed legacy or ambiguous types that conflicted with current v1 response shapes.

4) New v1 domain models (commit: 1553de1)

• Added models for previously uncovered unified API v1 domains:
  • Calendars,
  • ID mappings,
  • Template import,
  • View options,
  • Workspace filters,
  • Workspaces (including users, invites, limits, plans, and related request/response types).

5) Client contract redesign foundation (commit: cb3ad25)

• Updated IAdvancedTodoistClient, ITodoistClient, and ITodoistRestClient to support redesigned service contracts and endpoint usage patterns.
• Refactored command infrastructure (CommandServiceBase, ServiceBase, ITransaction, Transaction) for the new model.

6) Service layer migration to redesigned contracts (commit: e1a6bd5)

• Refactored service interfaces/implementations to match new model/query types and endpoint semantics.
• Introduced and/or renamed service contracts to better reflect domain behavior (IBackupsService, IEmailsService, IUploadsService, ITemplatesService, etc.).
• Moved notifications from legacy LiveNotifications service grouping into dedicated Notifications services.

7) New service coverage for added v1 domains (commit: 4e04009)

• Added complete service contracts + implementations for:
  • Workspaces,
  • Workspace filters,
  • View options,
  • Calendars,
  • ID mappings.

8) Client finalization pass (commit: 2bfec13)

• Finalized TodoistClient service wiring and property surface for all redesigned/new services.
• Completed TodoistRestClient updates required by finalized contracts.
• Added style preference to avoid primary constructors in current codebase conventions.

Breaking changes (consumer impact)

This PR introduces additional breaking changes beyond Phase 1/2:

1. Public contract reshaping

   • Multiple service interfaces and method signatures changed to align with v1 request/query/response shapes.
   • Several service/interface names were updated (IBackupService → IBackupsService, IUploadService → IUploadsService, etc.).

2. Model type replacements and relocations

   • Large portions of model types were replaced, split, or moved into new domain folders.
   • Legacy wrapper/result types were replaced by redesigned request/response entities.

3. Sync/command abstraction changes

   • Sync response and command result internals were redesigned; consumers relying on prior internal structure must migrate.

4. Expanded API surface in v11

   • New public services/models for Workspaces, Workspace Filters, View Options, Calendars, and ID mappings are now part of the client surface.

Compatibility notes

• This phase prioritizes v1 correctness and maintainability over preserving legacy pre-v1 internal abstractions.
• As in earlier phases, migration retains API compatibility where feasible, but consumers should expect a broader v11 migration effort due to service/model contract redesign.

Commit map

1. 6fc69e6 — reorganize models/services by domain
2. 5bbd02e — redesign common models, sync responses, commands, and exception/guard foundations
3. d03ac70 — refactor domain models for v1 request/response/argument alignment
4. 1553de1 — add new domain models (workspaces, workspace filters, view options, templates, IDs, calendars)
5. cb3ad25 — redesign client and command-service base contracts
6. e1a6bd5 — refactor service layer to redesigned contracts/endpoints
7. 4e04009 — add new services for added v1 domains
8. 2bfec13 — finalize TodoistClient/TodoistRestClient integration and contracts

Notes for reviewers

• This PR intentionally bundles all remaining contract-level migration work to avoid chaining multiple additional breaking PRs for v11.
• A dedicated migration guide in release docs is recommended to help consumers move from v10.x to the finalized v11 API surface.

[AhmedZaki99]

@olsh
I am still working on tests, but since changes are so much in this PR, I thought that pushing changes early would help us save time in review.

README.md has not been updated yet either.

I have split changes into several commits that should help you review relevant changes together. Hope this helps.