//////////////// Install/Uninstall ////////////////////////////////////////////////

type AppDependentBreakage = {
  // id of the dependent app which will or did break (Stopped) given the action.
  id: string
  title: string
  iconUrl: string
}

POST /apps/:appId/install(?dryrun)

body: {
  version: string, //semver
}
response : ApiAppInstalledFull & { breakages:  AppDependentBreakage[] }



POST /apps/:appId/uninstall(?dryrun)

response : { breakages:  AppDependentBreakage[] }

/////////////////////////////// Store/Show /////////////////////////////////////////////////


type ApiAppAvailableFull = ... {
  // app base data
  id: string
  title: string
  status: AppStatus | null
  versionInstalled: string | null
  iconURL: string

  // preview data
  versionLatest: string
  descriptionShort: string

  // version specific data
  releaseNotes: string
  serviceRequirements: AppDependencyRequirement[]

  // other data
  descriptionLong: string,
  version: string[],
}

type AppDependencyRequirement = ... {
  //app base data (minus status + version installed)
  id: string
  title: string
  iconURL: string

  // dependency data
  optional: string | null
  default: boolean
  versionSpec: string
  description: string | null
  violation: AppDependencyRequirementViolation | null
}

type AppDependencyRequirementViolation =
  { name: 'missing'; suggestedVersion: string; } |
  { name: 'incompatible-version'; suggestedVersion: string; } |
  { name: 'incompatible-config'; ruleViolations: string; auto-configurable: boolean } | // (auto-configurable for if/when we do that)
  { name: 'incompatible-status'; status: AppStatus; }


// Get App Available Full
GET /apps/:appId/store

response: ApiAppAvailableFull


// Get Version Specific Data for an App Available
GET /apps/:appId/store/:version

response: {
  // version specific data
  releaseNotes: string
  serviceRequirements: AppDependencyRequirement[]
}

///////////////////////////// Installed/Show ///////////////////////////////////////////


type ApiAppInstalledFull {
  // app base data
  id: string
  title: string
  status: AppStatus | null
  versionInstalled: string | null
  iconURL: string

  // preview data

  // other data
  instructions: string | null
  lastBackup: string | null
  configuredRequirements: AppDependencyRequirement[] | null // null if not yet configured
}


// Get App Installed Full
GET /apps/:appId/installed

reseponse: AppInstalledFull