Implement Endpoint

Implement Endpoint

Implement one FreeAgent endpoint page end-to-end for this repository, including SDK models and wrappers, service methods, tests, sample app page and navigation sync, and README/API coverage updates.

If the entity already exists, retrofit it to current guardrails in the same run.

Required Inputs

• EntityName (required)
• DocsUrlOverride (optional FreeAgent docs URL)

Step 1 — Validate Entity and Inventory Operations

1. Resolve the docs index: https://dev.freeagent.com/docs/index
2. Validate that EntityName maps to a real docs page.
3. If no matching endpoint page exists, stop immediately and report the invalid entity.
4. If DocsUrlOverride is provided, validate and use that page.
5. Fetch the docs page and list every operation heading (## / ###) before planning — for example "List all categories", "Get a single category", "Create an income category", "Create a cost of sales category", "Update an admin expenses category". The unit of implementation is the documented operation heading, not the HTTP route alone.

Step 2 — Plan First (New or Retrofit)

1. Produce a concise implementation plan before editing code.
2. If the entity already exists, audit existing models and services against these guardrails:
   • Every serialised property has JsonPropertyName
   • Date-only API fields use DateOnly (not DateTime)
   • Timestamp fields use DateTimeOffset (not DateTime)
   • Constrained string fields are enums or strong value mappings with exact wire values
   • Response payloads use explicit wrapper/envelope models
   • Services validate wrappers and throw FreeAgentApiException on missing payload
3. Flag any guardrail violations as retrofit tasks in the plan.
4. Include in the plan:
   • Operation heading inventory from Step 1
   • A table mapping heading → HTTP route → SDK method → request type → allowed fields (new) or existing service gaps (retrofit)
   • Documented use-case variants — when the API docs describe multiple create/update shapes for the same route (for example income vs cost-of-sales categories), list each variant and the typed SDK method/request type it will map to
   • New files vs retrofit files (with specific violations listed)
   • Breaking API-surface changes expected
   • Test, sample app, and documentation changes

Proceed to implementation only after the plan is complete.

Step 3 — Models and Guardrails

Apply to all new and retrofitted models:

1. Use System.Text.Json.
2. Every serialised/deserialised property must have JsonPropertyName.
3. Use DateOnly for date-only API fields.
4. Use DateTimeOffset for timestamp fields (not DateTime).
5. Constrained string fields must use enums or strong value mappings with exact wire-value behaviour.
6. API-facing enums must use explicit JsonStringEnumMemberName wire values for each enum member.
7. When docs are ambiguous for constrained values, do not silently guess; mark unresolved mapping and add a follow-up issue.
8. Response payloads must use explicit wrapper/envelope models.
9. Missing required payload branches must throw FreeAgentApiException.
10. Per-variant allowed values: when allowed wire keys differ by operation variant, use a distinct enum on that request only. When they also differ by a documented discriminator (for example company type), use discriminator-specific enums and factory methods — do not flatten into one enum, do not leave string plus "see the API docs", and do not add a runtime validator that fetches Company or account settings. See adr-0010-documented-operations-to-sdk-methods.md.

Common retrofit violations:

• DateTime instead of DateOnly for date-only fields
• DateTime instead of DateTimeOffset for timestamps
• String fields that should be enums per API docs
• Missing JsonPropertyName
• Response wrappers not validated in service methods
• Generic create/update payload that unions all variant attributes

Step 4 — Services and Pagination

1. Follow existing service structure under src/FreeAgent.Client/Services/.
2. Keep methods async and accept CancellationToken.
3. When the API paginates list results, provide both single-page and auto-pagination methods. Do not invent pagination for endpoints that return a complete collection (for example Categories).
4. Where the API accepts per_page, respect the FreeAgent maximum of 100 and fail fast if the caller exceeds it.
5. Documented use-case variants: when the API docs describe multiple create or update shapes for the same HTTP route, expose a separate public request type and service method per variant (for example CreateIncomeCategoryAsync, CreateCostOfSalesCategoryAsync). Each request type must include only the attributes allowed for that variant. Fixed wire values such as category_group are set by the SDK — callers must not supply them. Do not expose a single generic create/update that forces consumers to read external docs to learn which fields apply.
6. Documented local contract checks: fail fast only on constraints the official docs state that do not require account state. Do not invent extra validation, uniqueness checks, or fetches of Company/settings. Categories nominal-code ranges are one documented example, not a pattern to copy onto undocumented fields.

Step 5 — Tests

Add or update tests to cover:

• URL construction
• Envelope/wrapper deserialisation
• Date handling (DateOnly)
• Enum/string wire mapping exactness
• Missing payload branch exceptions
• Pagination behaviour and cancellation when the API paginates
• At least one test per documented write variant — assert URL, envelope, and which fields are included or excluded in the serialised payload

Step 6 — Sample App Sync

Follow the probe-page standard documented in docs/contributing/sample-probe-pages.md. Use Company (single GET), Contacts (paginated list + CRUD), and Categories (non-paginated list + multi-variant writes) as reference implementations.

1. Add or update page(s) under samples/FreeAgent.Client.BlazorSample/Components/Pages/.
2. Update navigation in samples/FreeAgent.Client.BlazorSample/Components/Layout/MainLayout.razor.
3. Do not add sample UI for endpoints not implemented in SDK.
4. On each probe page, include:
   • EndpointProbeHeader (call under test, DocsUrl, environment, endpoint path)
   • ModelProbeResults built via ModelWireDiagnostics.Build(...) after successful SDK calls
   • ApiErrorDiagnostics on failures
   • A readable raw JSON section (provided by ModelProbeResults)
5. For list endpoints: per-row mapping inspection from the wire array item (see Contacts.razor).
6. For CRUD endpoints: detail page with ?id= deep links; fetch wire JSON after create/update; show MudProgressLinear while operations run (see ContactDetail.razor).
7. When the SDK exposes multiple write variants for the same resource, the sample must be able to invoke each public write method — a variant selector on one CRUD page is sufficient; exercising only one variant (for example income-only) is not.
8. Add seed fixtures when demo data helps field coverage (narrative canon and/or a full-detail probe contact); upsert by a stable natural key when re-running should refresh existing records.
9. Only model wire fields that appear in the official FreeAgent API docs.

Update samples/README.md and docs/reference/api-coverage.md in the same change.

Step 7 — Documentation

Update the root README.md, src/FreeAgent.Client/README.md (API coverage, usage examples), docs/reference/api-coverage.md, and any affected plan or entity-map sequencing docs.

Step 8 — Validation

Run from repository root:

dotnet build
dotnet test

Highlight any breaking changes applied during retrofit (DateTime → DateOnly, string → enum).

References

• adr/adr-0010-documented-operations-to-sdk-methods.md
• docs/contributing/sample-probe-pages.md
• plan/IMPLEMENTING_ENDPOINTS.md
• plan/API_TYPE_MAPPING_POLICY.md
• plan/API_TO_SDK_ALIGNMENT.md
• CONVENTIONS.md
• AGENTS.md