Merge branch 'dev'

Author: kaiser-jan

.releaserc

@@ -45,7 +45,7 @@
 					{
 						"path": "dist/untis.js",
 						"label": "${branch.prerelease ? '⚠️ BETA ⚠️ ' : ''}Scriptable Untis Widget ${nextRelease.gitTag}",
-						"name": "UntisWidget${branch.prerelease ? '-Beta' : ''}.scriptable"
+						"name": "UntisWidget${branch.prerelease ? '-Beta' : ''}.js"
 					}
 				]
 			}

README.md

@@ -7,17 +7,18 @@ iOS Widgets for [Untis](https://webuntis.com/) using [Scriptable](https://script
 
 ## ❔ What is this for?
 
-Untis is a service used by many students to keep track of their school-life, especially for checking the timetable.
-There is a mobile app, but it does not provide any widgets.
+Untis is a service used by many students (mainly in Austria and Germany) to keep track of their school-life, especially for checking the timetable.
+There is a mobile app, but it does not provide any widgets, at least on iOS.
 That's why I decided to create those widgets myself, so I can have the most important information directly on my homescreen.
+It also notifies me about the most important changes.
 
 ## ✨ Features
 
 The script allows you to display data for one WebUntis account in a widget, and will notify you about important changes.\
 You can set what information (views) should be displayed for each widget.\
 To safe battery and bandwidth, the data is updated at the start of every lesson and every few hours outside of school-hours.\
 The fetched data is cached for some time, so the script takes less time, bandwidth and battery to run.\
-Many things can be configured via the visual config editor or the configuration file `untis-config.json` in the scriptable folder, check the [configuration section](#⚙️-configuration) for details.
+Many things can be configured via the visual config editor or the configuration file `untis-config.json` in the scriptable folder, check the [configuration section](#⚒️-configuration) for details.
 
 ### 🔔 Notifications
 
@@ -41,86 +42,102 @@ After a school day has ended, a summary of the next day is displayed. (list of s
 #### Exams
 
 Shows the upcoming exams, meaning their subject and date.
+By default, exams are colored according to the subject configuration. The widget displays as much information as fits.
 You can configure how many days ahead the exams should be displayed and set a maximum count.
 
 #### Grades
 
 Displays the recent grades you received. (subject + mark)
+By default, grades are colored according to the subject configuration. The widget displays as much information as fits.
 You can configure how long grades should be displayed and set a maximum count.
 
 #### Absences
 
-Lists open (unexcused) absences with their date and duration.
+Lists open (unexcused) absences with their date and duration. It also shows who created the absence, if there is enough space.
 
 ## 📥 Installation
 
-1. Before installing the script, you need to [install Scriptable from the AppStore](https://apps.apple.com/us/app/scriptable/id1405459188?uo=4).
+1. Before installing the script, you need to [install Scriptable from the App Store](https://apps.apple.com/us/app/scriptable/id1405459188?uo=4).
 
 2. To install the script, head over to the [releases page](https://github.com/JFK-05/scriptable-untis/releases) select the latest release.\
-   If you always want to check out the latest features, which might not be stable, you can download the beta release.\
-   Alternatively, you can download the latest stable release [here](https://github.com/JFK-05/scriptable-untis/releases/latest/download/UntisWidget.scriptable).
+   Alternatively, you can directly download the latest stable release [here](https://github.com/JFK-05/scriptable-untis/releases/latest/download/UntisWidget.scriptable).
 
-3. After downloading the file, you can click to open it with scriptable.
-   This will add the script to the list.
+3. After downloading the file, click share, and select scriptable.
+   Now click `Add to My Scripts` at the bottom.
 
-4. Open Scriptable, click the script to run it.
-   You will be asked what you want to do.
-   Select `🔑 Change Credentials` and enter your WebUntis credentials as prompted.\
-   You will be asked for the url, which you can find when selecting you school [here](https://arche.webuntis.com/WebUntis/?school=litec#/basic/login). You might have to click the "switch school" button to get to the correct page. The url should look something like this: `https://<server>.webuntis.com/WebUntis/?school=<schoolname>#/basic/login`. (with `<server>` and `<schoolname>` replaced)
+4. Click the play button at the lower right (or click the script in the overview) to run the script. This will start the setup process.\
+   You will be asked for the url, which you can find when selecting you school [here](https://webuntis.com/). You might have to click the "switch school" button to get to the correct page.\
+   The url should look something like this: `https://<server>.webuntis.com/WebUntis/?school=<schoolname>#/basic/login`. (with `<server>` and `<schoolname>` replaced)
 
-5. Now you can add an IOS widget for Scriptable and select the script in the options.
+5. Now you can add an iOS widget for Scriptable and select the script in the options.
 
-6. The widget should update automatically and display the information. 🥳
+6. The widget should update automatically and display the information. 🥳 (might take a few seconds)
 
-7. If you want to customize the widget (e.g. color the lessons, see the [configuration section](#⚙️-configuration))
+7. If you want to customize the widget (e.g. color the lessons), see the [configuration section](#⚒️-configuration).
 
-## ⚙️ Configuration
+## ⏫ Updating
+
+The script will check for updates every few hours.\
+Regular updates will be downloaded and installed automatically.\
+If you want to update manually, you can do so by running the script and selecting `🔄 Update Script` in the menu.\
+When there is a breaking change, you will be notified and asked to update manually.\
+Check the [releases page](https://github.com/JFK-05/scriptable-untis/releases) for more information about the changes.
+
+## ⚒️ Configuration
 
 When long-pressing the widget, you see the iOS widget configuration.
 In the `Parameter` field, you can enter the configuration for the widget.
 The configuration is a list of the views you want to be displayed, separated by a comma.\
 For larger widgets, you can create multiple columns by separating the views with a pipe (`|`).\
 Example: `lessons,exams` or `lessons|exams,grades,absences`
 
-### ⚒️ Config Editor
+### ⚙️ Settings Editor
 
-The config editor is a UI utility, so you don't have to deal with the configuration file directy.\
-You can open it by running the script and selecting `⚒️ Config Editor` in the menu.\
+The config editor is a UI utility, so you don't have to deal with the configuration file directly.\
+You can open it by running the script and selecting `⚙️ Open Settings` in the menu.\
 It will open up a list with settings categories. The top row shows you where you are in the menu, below there are the categories and settings.\
 Clicking a category will open it, clicking a setting will open a dialog to edit it.\
+If you change a value, the default will be displayed below it in gray.\
 You can use the `↩️` button to reset a setting to its default value.
 
 #### 📚 Subjects Config
 
 The subjects config allows you to configure e.g. the colors of the lessons.\
 It is accessible in the config editor under `📚 Subjects Config`.\
-You will now see a list of all subjects you have configurations for. (might be empty)
+You will now see a list of all subjects you have configurations for, listed by their short name. (might be empty)\
+You can delete a subject config by clicking the trash emoji (🗑️).
+
+By clicking a subject, you can open its specific configuration.
 
 Here are the configuration options:
 
--   `color`: The color of the lesson. This can be a hex code (like `#ff0000`) or a color name (like `red`).
+-   `color`: The color of the lesson. You can either enter a hex code (like `#ff0000`) at the top, or select one from the palette.
     To find the perfect color, you can use [this website](https://htmlcolorcodes.com/color-picker/).
     Darker, less saturated colors are recommended, as this makes it easier to read the white text on the background.
--   `teacher`: The name of the teacher to apply this config for. This is only available, if you specified a teacher when adding the subject.
--   `custom short name`: The short name of the subject to display.
--   `custom long name`: The name of the subject to display if there is enough space (and the option is enabled).
+-   `short name`: The short name of the subject to display.
+-   `long name`: The name of the subject to display if there is enough space (and the option is enabled).
 -   `ignore infos`: A list of lesson infos to ignore. This can be useful if there is lesson info which is always there.
     This should be a comma-separated list of the infos to ignore, wrapped in double quotes. (`"infoName"` or `"info1", "info2"`)
 
-#### Adding a new subject
+##### Adding a new subject
 
 At the top you can add a new subject configuration. You will have to enter the `short subject name` (the one displayed in webuntis.)\
 If you want to only apply the configuration when a specific teacher is teaching the subject, you can enter the `teacher` name as well.
 This can be helpful when there are subjects which are combined in WebUntis.
 
+##### 🧑‍🏫 Teacher specific configs
+
+Some subjects may be combined in Untis. For example, geography and history may be combined.\
+In the teachers section of a subject, you can create configs for specific teachers.\
+When this teachers now teaches this subject, the configuration of the teacher will override the one from the subject.
+
 ### 📄 Config File
 
 The configuration file `untis-config.json` is located in the scriptable folder.\
 A default configuration file is created when the script is run for the first time. Check it out to see what's possible!\
-Changes to the configuration file are applied when the script is run again.\
-I am aware that editing this json file is not the most user-friendly way, I am considering adding a visual configuration tool.
+Changes to the configuration file are applied when the script is run again.
 
-## 🧑‍💻 A Note for Developers
+## 🧑‍💻 Notes for Developers
 
 ### 📦 Bundling
 
@@ -134,4 +151,10 @@ That's why I switched to [rollup](https://rollupjs.org/), which worked perfectly
 ### ⚙️ Config Editor
 
 The config editor is a handy utility which makes the widget easier to use for people, who are not into editing config files.\
-But of the limitations of scriptable, and as the implementation had to be quite generalizable, the code is a little complex.
+But of the limitations of scriptable, and as the implementation had to be quite generalizable, the code is a little complex.\
+I am quite happy with the result, even though it has a few flaws, which I might address in the future.
+
+### 📖 Documentation
+
+Currently there seems to be an issue with github (similar to [this one](https://github.com/thlorenz/anchor-markdown-header/issues/36)), where emojis in titles break header links.\
+Therefore the header anchors in this readme may not work.

index.ts

@@ -1,17 +1,34 @@
 import { clearCache, prepareUser } from '@/api/cache'
-import { PREVIEW_WIDGET_SIZE, SCRIPT_START_DATETIME } from '@/constants'
+import {
+	GITHUB_REPO,
+	GITHUB_SCRIPT_NAME,
+	GITHUB_USER,
+	PREVIEW_WIDGET_SIZE,
+	SCRIPT_START_DATETIME,
+	UPDATE_INTERVAL,
+} from '@/constants'
 import { getLayout } from '@/layout'
 import { openSettings } from '@/settings/editor/settingsEditor'
-import { writeKeychain } from '@/setup'
-import { createErrorWidget, ExtendedError, SCRIPTABLE_ERROR_MAP } from '@/utils/errors'
+import { fillLoginDataInKeychain } from '@/setup'
+import { createErrorWidget, ExtendedError, handleError, isExtendedError, SCRIPTABLE_ERROR_MAP } from '@/utils/errors'
 import { getModuleFileManager as getFileManagerOptions, readConfig } from '@/utils/scriptable/fileSystem'
-import { selectOption } from '@/utils/scriptable/input'
+import { selectOption, showInfoPopup } from '@/utils/scriptable/input'
+import { KeychainManager } from '@/utils/scriptable/keychainManager'
+import { checkForUpdates, checkForUpdatesWith, shouldCheckForUpdates } from '@/utils/updater'
 import { createWidget } from '@/widget'
 
-// TODO: Auto-Update
-// store the last update date in the keychain
-// check every day (store the last check date in the keychain)
-// compare the last update date with the date from the github api
+// initialize the keychain manager
+new KeychainManager('untis')
+
+// check for updates (in a try-catch block to prevent the script from crashing if the update fails)
+try {
+	if (shouldCheckForUpdates(UPDATE_INTERVAL)) {
+		await checkForUpdates()
+	}
+} catch (error) {
+	console.error('⏫❌ Could not check for updates.')
+	log(error)
+}
 
 async function setupAndCreateWidget() {
 	const { useICloud, fileManager } = getFileManagerOptions()
@@ -21,51 +38,61 @@ async function setupAndCreateWidget() {
 	return widget
 }
 
+async function presentWidget() {
+	const widget = await setupAndCreateWidget()
+	switch (PREVIEW_WIDGET_SIZE) {
+		case 'small':
+			widget.presentSmall()
+			break
+		case 'medium':
+			widget.presentMedium()
+			break
+		case 'large':
+			widget.presentLarge()
+			break
+	}
+}
+
+function showDocumentation() {
+	console.log('📖 Opening documentation in Safari.')
+	Safari.openInApp('https://github.com/JFK-05/scriptable-untis#readme')
+}
+
 enum ScriptActions {
 	VIEW = '💻 Show Widget',
-	CHANGE_CREDENTIALS = '🔑 Change Credentials',
-	EDIT_CONFIG = '🛠️ Edit Config',
-	CLEAR_CACHE = '🗑️ Clear Cache',
+	OPEN_SETTINGS = '⚙️ Open Settings',
+	// CHANGE_CREDENTIALS = '🔑 Change Credentials',
+	// UPDATE = '⏫ Update Script',
+	// CLEAR_CACHE = '🗑️ Clear Cache',
 	SHOW_DOCUMENTATION = '📖 Open Documentation',
 }
 
+const actionMap: Record<ScriptActions, Function> = {
+	[ScriptActions.VIEW]: presentWidget,
+	// [ScriptActions.CHANGE_CREDENTIALS]: fillLoginDataInKeychain,
+	[ScriptActions.OPEN_SETTINGS]: openSettings,
+	// [ScriptActions.CLEAR_CACHE]: clearCache,
+	[ScriptActions.SHOW_DOCUMENTATION]: showDocumentation,
+	// [ScriptActions.UPDATE]: checkForUpdates,
+}
+
 async function runInteractive() {
 	const actions = Object.values(ScriptActions).filter((item) => {
 		return isNaN(Number(item))
 	})
 
-	const input = await selectOption(actions, {
+	const input = (await selectOption(actions, {
 		title: 'What do you want to do?',
-	})
+	})) as ScriptActions | null
 
-	switch (input) {
-		case ScriptActions.VIEW:
-			const widget = await setupAndCreateWidget()
-			switch (PREVIEW_WIDGET_SIZE) {
-				case 'small':
-					widget.presentSmall()
-					break
-				case 'medium':
-					widget.presentMedium()
-					break
-				case 'large':
-					widget.presentLarge()
-					break
-			}
-			break
-		case ScriptActions.CHANGE_CREDENTIALS:
-			await writeKeychain()
-			break
-		case ScriptActions.EDIT_CONFIG:
-			await openSettings()
-			break
-		case ScriptActions.CLEAR_CACHE:
-			clearCache()
-			break
-		case ScriptActions.SHOW_DOCUMENTATION:
-			Safari.openInApp('https://github.com/JFK-05/scriptable-untis#readme')
-			break
+	const action = actionMap[input]
+
+	if (!action) {
+		console.log('No action selected, exiting.')
+		return
 	}
+
+	await action()
 }
 
 try {
@@ -76,28 +103,7 @@ try {
 		await runInteractive()
 	}
 } catch (error) {
-	// throw the error if it runs in the app
-	if (config.runsInApp) {
-		throw error
-	}
-
-	let widget: ListWidget
-	const castedError = error as Error
-
-	const scriptableError = SCRIPTABLE_ERROR_MAP[castedError.message.toLowerCase()]
-	log(scriptableError)
-	if (scriptableError) {
-		widget = createErrorWidget(scriptableError.title, scriptableError.description, scriptableError.icon)
-	} else {
-		const extendedError = error as ExtendedError
-		widget = createErrorWidget(extendedError.name, extendedError.message, extendedError.icon)
-	}
-
-	if (!config.runsInWidget) {
-		widget.presentLarge()
-	}
-
-	Script.setWidget(widget)
+	handleError(error)
 }
 
 console.log(`Script finished in ${new Date().getTime() - SCRIPT_START_DATETIME.getTime()}ms.`)

package.json

@@ -13,9 +13,9 @@
 		"@semantic-release/release-notes-generator": "^10.0.3",
 		"semantic-release": "^21.0.1",
 		"@rollup/plugin-typescript": "^11.1.0",
-		"rollup": "^3.20.2",
+		"@types/scriptable-ios": "^1.7.0",
+		"rollup": "^3.20.3",
 		"tslib": "^2.5.0",
-		"typescript": "^5.0.3",
-		"@types/scriptable-ios": "^1.7.0"
+		"typescript": "^5.0.4"
 	}
 }