@spec clear_all() :: :ok

Clears all state.

@spec create_finance_application(integer()) ::
  {:ok, struct()} | :not_found | {:error, term()}

Creates a finance application linked to the given campaign. Returns the inserted %FinanceApplication{} struct.

@spec create_referral(map()) :: {:ok, map()} | {:error, term()}

Creates a new referral with all associated resources.

@spec get_campaign(integer()) :: {:ok, map()} | :not_found

Retrieves a campaign by ID.

@spec get_finance_application(integer()) :: {:ok, struct()} | :not_found

Retrieves a finance application by ID.

@spec get_referral(integer()) :: {:ok, map()} | :not_found

Retrieves a referral by ID with all associated data.

@spec list_referrals() :: [map()]

Lists all referrals.

@spec update_campaign_status(integer(), String.t()) ::
  {:ok, struct(), String.t()} | :not_found | {:error, term()}

Updates a campaign's status. Returns the updated campaign struct along with the previous status so callers can build webhook payloads.

This is the low-level DB operation. Callers that want the matching campaign_status_change webhook to fire should use update_campaign_status_and_notify/2 instead.

@spec update_campaign_status_and_notify(integer(), String.t()) ::
  {:ok, map()} | :not_found | {:error, term()}

Updates a campaign's status AND enqueues the matching campaign_status_change webhook for delivery.

This is the high-level orchestration that mirrors what the real CampaignFlow service does internally when a status changes — both the POST /campaigns/:id/set-status API handler and the MockServer.Test.set_campaign_status/2 test helper route through it.

Returns {:ok, campaign} on success — the API-shaped response map, ready to be JSON-encoded by the handler.

@spec update_finance_application_status(integer(), String.t()) ::
  {:ok, struct(), String.t()} | :not_found | {:error, term()}

Updates a finance application's status. Returns the updated record along with the previous status.

This is the low-level DB operation; callers that want the matching finance_application_status_change webhook to fire should use update_finance_application_status_and_notify/2 instead.

@spec update_finance_application_status_and_notify(integer(), String.t()) ::
  {:ok, struct()} | :not_found | {:error, term()}

Updates a finance application's status AND enqueues the matching webhooks for delivery.

Always enqueues a finance_application_status_change event. Additionally, when a finance application transitions TO "waiting-approval" from a different status, this function applies the documented state-machine side-effect: the linked campaign auto-advances to "waiting-finance" (unless it's already in that status), and a separate campaign_status_change event is enqueued.

Webhook order (newest last in the DB): finance_application_status_change, then campaign_status_change if a side-effect happened.

@spec valid_campaign_statuses() :: [String.t()]

The set of valid campaign statuses defined by the OpenAPI Campaign schema enum.

@spec valid_finance_application_statuses() :: [String.t()]

The set of valid finance application statuses defined by the OpenAPI SetFinanceApplicationStatusRequest enum.