Document API client integration and migration guide

epic-bufdir-report-export-api-integration-task-010 — Write technical documentation for the bufdir-api-client covering: the shared interface contract between file-based and API submission paths, authentication setup and credential rotation steps, how to enable direct_api mode per organisation via the feature flag, the BufdirSubmissionResult model and error type catalogue, and a migration checklist for organisations transitioning from file-based to direct API submission once Norse Digital Products completes API negotiations with Bufdir.

low priority low complexity documentation pending documentor Tier 5

Acceptance Criteria

A markdown document exists at `docs/bufdir-api-client.md` (or equivalent agreed location) covering all six specified topic areas

The shared interface contract section specifies the abstract Dart class or interface name, every method signature, and the behavioural guarantee that both file-based and API submission implementations honour

The authentication setup section includes step-by-step instructions for storing credentials in Supabase Vault (or the agreed secret store) and the exact environment variable / Supabase config key names expected by the client

The credential rotation section explains how to rotate the API secret without downtime, including the sequence of Supabase config updates and any cache-invalidation steps

The feature flag section documents the exact flag key name, the Supabase table/config location where it is set, the valid values (e.g., `file_based` vs `direct_api`), and how to toggle it per organisation without redeploying

The BufdirSubmissionResult section documents every field (reference_number, submitted_at, status) with Dart types and nullable/non-nullable annotations

The error catalogue section documents every typed exception (BufdirValidationException, BufdirServerException, AuthenticationException) with: trigger conditions, fields available on the exception object, and recommended coordinator-facing error messages

The migration checklist is a numbered list that an NHF/HLF/Blindeforbundet coordinator or their Norse Digital Products contact can follow step by step, ending with a verification step confirming the first API submission succeeded

A tech lead from Norse Digital Products has reviewed the document and confirmed it is accurate and complete before the epic is closed

Technical Requirements

frameworks

Dart (documentation via DartDoc comments is supplementary but not the primary deliverable)

Markdown

apis

Bufdir API (document endpoint URLs, auth scheme, and payload schema as known at time of writing; note any TBD sections explicitly)

data models

BufdirSubmissionResult

BufdirValidationException

BufdirServerException

AuthenticationException

performance requirements

Documentation must be accurate as of the current implementation — no speculative or future-state content without explicit labelling

security requirements

No real credentials, tokens, or organisation IDs in examples — use placeholder values like `<YOUR_API_KEY>`

Explicitly warn readers not to commit credentials to source control; point to the Supabase Vault setup guide

Execution Context

Execution Tier

Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

Integration Task

Handles integration between different epics or system components. Requires coordination across multiple development streams.

View Full Execution Plan

Implementation Notes

Write the document in a tone suitable for both a developer implementing the integration and a non-developer project coordinator following the migration checklist. Use numbered lists for procedures, code blocks for all Dart snippets and shell commands, and admonition blocks (Note/Warning) for security-sensitive steps. Keep the migration checklist in a separate clearly labelled section so it can be extracted and sent to organisation contacts as a standalone document. Mark all sections that depend on Bufdir finalising the API contract with a `[PENDING: Bufdir API negotiation]` tag so reviewers know these sections require updating.

Store the document in the project repository so it is versioned alongside the code.

Testing Requirements

Documentation review rather than automated tests. The tech lead must verify: (1) every code snippet compiles or runs correctly against the actual implementation, (2) credential rotation steps are walked through in a staging environment to confirm they work without errors, (3) the feature flag toggle is tested against a real organisation record in staging to confirm it routes to the correct submission path. If any snippet is found to be incorrect during review, the doc must be updated before the task is marked done.

Component

Bufdir API Client

service high

Dependencies (3)

Implement secure storage and rotation of Bufdir API credentials within the bufdir-api-client. Credentials must be stored in the integration credential vault (not in source code or plain config files), support rotation without service restart, and enforce org-level isolation so credentials for one organisation cannot be accessed by another. Provide a rotation procedure document. epic-bufdir-report-export-api-integration-task-008 Wire the bufdir-api-client into the bufdir-export-service submission routing. When submission_mode is direct_api, call bufdir-api-client.submit() instead of the file generation path. Ensure the orchestration layer interface is unchanged, pass the canonical payload from bufdir-format-serializer to the client, and propagate the BufdirSubmissionResult back to the calling screen for confirmation display. epic-bufdir-report-export-api-integration-task-007 Write comprehensive tests for the bufdir-api-client: unit tests for the request mapper covering all required and optional payload fields, unit tests for authentication token refresh and error handling, integration tests using a mock Bufdir API server to validate the full submission flow (success, 422 validation error, 500 retry), and tests confirming the bufdir_reference_number is correctly persisted. Target 90%+ coverage on the client module. epic-bufdir-report-export-api-integration-task-009

Epic Risks (2)

medium impact high prob dependency

Norse Digital Products has not yet completed API negotiations with Bufdir. If negotiations stall or Bufdir's API design diverges significantly from expectations, the API client may need substantial rework, or the epic may be blocked indefinitely.

Mitigation & Contingency

Mitigation: Implement the client against a locally defined stub of the expected Bufdir API schema. Isolate all Bufdir-specific schema mapping in a single adapter class so that changes to the actual API schema require changes in only one place. Keep the epic in 'interface-ready' status until real API credentials are available for integration testing.

Contingency: If API negotiations are not completed within the planned window, defer this epic without impact on any other epic — the PDF/CSV fallback path from Epics 1–4 delivers full standalone value. Mark the epic as blocked and resurface when negotiations conclude.

high impact low prob security

Bufdir API credentials stored in the application or edge function environment could be exposed through misconfigured secrets management, log leakage, or a compromised deployment pipeline, allowing unauthorised Bufdir submissions on behalf of the organisation.

Mitigation & Contingency

Mitigation: Store all Bufdir API credentials exclusively in Supabase Vault (or the integration credential vault component), never in client-side code or environment variables accessible to the Flutter app. Transmit credentials only from within the edge function, not from the Flutter client. Implement credential rotation support from the outset.

Contingency: If a credential leak is detected, immediately revoke and rotate the affected API credentials through Bufdir's credential management portal, audit submission logs for any unauthorised calls, and notify Bufdir's technical contact per the API agreement's security incident clause.

Quick Links

All Tasks Execution Plan