@spec activate(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Installation.t()} | {:error, ArchAstro.Error.reason()}

Activate an installation

Transitions an installation from a pending or paused state to active, enabling the agent to receive events and process work through the installed integration or enablement channel.

Activation requires that the installation already has a bound integration (either via shared_integration or an inline integration created at install time). If no integration is bound, the request returns 422. The caller must have app scope for the app that owns the installation.

The updated installation with state reflecting the new active status.

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Delete an installation

Permanently deletes an installation and severs the connection between the agent and the external service or enablement channel. Any backing context sources associated with the installation are also removed.

This action is irreversible. If you want to temporarily stop an installation from processing events, use the Pause or Suspend endpoints instead. The caller must have app scope for the app that owns the installation.

Empty response with HTTP 204 status on successful deletion.

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Installation.t()} | {:error, ArchAstro.Error.reason()}

Retrieve an installation

Returns a single installation by ID. Use this endpoint to check the current state, kind, config, and bound integration of an installation.

The installation must belong to an agent that is accessible within the authenticated app's scope. The caller must have app scope for the app that owns the installation.

The requested installation.

@spec list(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1AgentInstallations.Params.t()
) ::
  {:ok, ArchAstro.Types.InstallationListResponse.t()}
  | {:error, ArchAstro.Error.reason()}

List installations for an app

Returns all installations across every agent in the authenticated app. Use this endpoint to get a global view of all external service and enablement channel connections for the app.

Optionally narrow results to a single agent by passing the agent parameter. To list installations scoped to a specific agent, you may also use the per-agent List Installations endpoint. Results are returned as an unordered array with no pagination. The caller must have app scope.

The list of installations for the app, optionally filtered by agent.

@spec pause(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Installation.t()} | {:error, ArchAstro.Error.reason()}

Pause an installation

Transitions an active installation to the paused state, temporarily stopping the agent from receiving events through this installation. The installation and its integration binding are preserved and can be resumed by calling the Activate endpoint.

Only installations in the active state can be paused. Attempting to pause an installation in any other state returns 422. The caller must have app scope for the app that owns the installation.

The updated installation with state set to "paused".

@spec suspend(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1AgentInstallationsInstallationSuspend.Input.t()
) ::
  {:ok, ArchAstro.Types.Installation.t()} | {:error, ArchAstro.Error.reason()}

Suspend an installation

Transitions an installation to the suspended state, disabling event processing and signaling that the installation requires administrative attention. Unlike pausing, suspension typically indicates a policy or compliance hold rather than a temporary operational stop.

An optional reason string can be supplied to record why the installation was suspended; this is stored on the installation and visible when you retrieve it. Only installations that are not already suspended can be suspended — sending this request for an already-suspended installation returns 422. The caller must have app scope for the app that owns the installation.

The updated installation with state set to "suspended".