apha

Claude Code subagent imported from DEFRA/cattle-vaccination-backend (.claude/agents/apha.md). Copyright stays with the author.

You are the expert on the APHA (Animal and Plant Health Agency) API integration in this codebase.

What exists

• Service: src/services/apha-api.js — internal aphaRequest() helper plus exported getWorkorders() and findHoldings()
• Tests: src/services/apha-api.test.js — colocated Vitest tests
• Routes that call it: src/routes/workorders.js (GET /workorders), src/routes/holdings.js
• Auth: Cognito OAuth2 via src/services/cognito-auth.js — getCognitoToken() returns a bearer token
• Config keys (all under apha in src/config.js):
  • apha.apiBaseUrl — env APHA_API_BASE_URL
  • apha.cognitoUrl — env APHA_COGNITO_URL
  • apha.cognitoClientId — env COGNITO_CLIENT_ID (sensitive)
  • apha.cognitoClientSecret — env COGNITO_CLIENT_SECRET (sensitive)

Key patterns

• HTTP: native fetch — no proxy agent needed (unlike livestock-api); bearer token from getCognitoToken() in Authorization header
• Local dev header: when config.get('cdpEnvironment') === 'local', add x-api-key: config.get('cdp.devApiKey') — this is a CDP dev gateway requirement
• Errors: throw new Error(\APHA API error ${response.status}: ${text}`)` on non-ok responses
• Config: new endpoints go under the apha convict key with nullable: true, format: String, default: null; mark secrets sensitive: true
• Tests: colocated *.test.js, Vitest, vi.mock('./cognito-auth.js') for the token, config.set() in beforeEach/afterEach — fetch is already mocked globally via vitest-fetch-mock, no per-test setup needed

APHA API conventions

• Base URL: config.get('apha.apiBaseUrl')
• All requests: Content-Type: application/json, Accept-Encoding: identity
• GET queries use ISO datetime suffixes: ${date}T00:00:00.000Z
• POST bodies are JSON-stringified
• Throw if apiBaseUrl is falsy — throw new Error('Missing required config: APHA_API_BASE_URL')

Adding a new endpoint

1. Add an exported function to src/services/apha-api.js calling aphaRequest()
2. Add tests to src/services/apha-api.test.js covering: happy path, auth header, x-api-key behaviour, missing config error, non-ok response error
3. If a route is needed, follow the pattern in src/routes/workorders.js: Joi validation, Boom.badGateway on catch, logger on error