pcli/openspec/changes/archive/2026-02-11-replace-auth-with-api-key/specs/api-client/spec.md

MODIFIED Requirements

Requirement: Base HTTP client

The system SHALL provide a base HTTP client that sends requests to the Planka API. The client SHALL construct URLs by joining the configured base URL with the API path. The client SHALL attach an x-api-key: <key> header to every request. The client SHALL send and receive JSON (Content-Type: application/json). The client SHALL accept a *slog.Logger and log every request at DEBUG level with method, path, status code, and duration. The client SHALL log errors at WARN level.

Scenario: Successful API request

• WHEN the client sends a request to a valid endpoint
• THEN the response body SHALL be returned as parsed JSON
• AND the request SHALL include the x-api-key header
• AND a DEBUG log entry SHALL be emitted with method, path, status, and duration

Scenario: API returns error status

• WHEN the API responds with a 4xx or 5xx status code
• THEN the client SHALL return an APIError containing the HTTP status code and response message
• AND a WARN log entry SHALL be emitted

Scenario: Network failure

• WHEN the HTTP request fails due to a network error (connection refused, timeout, DNS failure)
• THEN the client SHALL return a Go error wrapping the underlying network error

Requirement: Authentication from environment

The system SHALL read PLANKA_URL from the environment to determine the API base URL. The system SHALL read PLANKA_API_KEY from the environment to determine the API key. Global flags --url and --api-key SHALL override the corresponding environment variables. Flag values SHALL take precedence over environment variables.

Scenario: Auth from environment variables

• WHEN PLANKA_URL and PLANKA_API_KEY are set in the environment
• AND no --url or --api-key flags are provided
• THEN the client SHALL use the environment variable values

Scenario: Flag overrides environment

• WHEN --url or --api-key flags are provided
• THEN the flag values SHALL take precedence over environment variables

Scenario: Missing configuration

• WHEN neither the environment variable nor the flag is set for URL or API key
• THEN the system SHALL print an error message and exit with code 1