Welcome to PatchKit Launcher SDK API Documentation.

Here you can find information on how to work with various packages that expose API for creating launchers based on PatchKit.

Programming Concepts

Multiple Packages Design

The API is split into multiple packages, each serving a different part of the stack.

• @upsoft/patchkit-launcher-foundation provides base interfaces and enums that are shared between the runtime and theme.
• @upsoft/patchkit-launcher-runtime-api-theme-client provides functions exposed by the runtime that can be called from the theme.
• @upsoft/patchkit-launcher-runtime-api-react-theme-client provides hooks that make API usage in React themes more convenient. It provides queries and mutations that are automatically synchronized and cached in your theme.
• @upsoft/patchkit-launcher-runtime-api-react-theme-extras provides extra hooks for React themes that supply additional non-core functionality like storing a task's progress history (if you want to display charts) or a simplified controller for app branches.

Procedural/Functional Design

The API is designed with procedural/functional programming concepts in mind. It is based on simple principles of functions and structures.

Named Parameters

Function parameters are always named. This means that if a function accepts arguments, you must provide them within an object.

startAppBranch({
  appId: `xyz`,
  appBranchId: `123`,
});
Copy

Async Nature

All functions exported from the runtime are asynchronous due to the nature of Electron's IPC communication. There are a few exceptions for this rule with functions like getAppBranchUid, which are synchronous due to not being IPC calls.

get* / fetch*/ retrieve* Function Differences

• Functions that start with get* are designed to be pure. This means that for the same input, they always provide the exact same output.
• Functions that start with fetch* are guaranteed to acquire information at the source, providing the always up-to-date state.
• Functions that start with retrieve* are allowed to utilize caching mechanisms, which means that the information they provide might be outdated.

*Info / *State Structure Differences

• Structures that end with *Info are designed to represent information that is either constant or changes very rarely. Due to that, it can be freely cached between sessions.
• Structures that end with *State are designed to represent information that changes often or is based on local system state and should not be cached between sessions under any circumstances.

Core Concepts

App

• Is based on an entry from the App Catalog to which the Launcher is linked.
• If the App Catalog entry is configured for the current Launcher platform, it contains at least one Branch with the id set to main.

App Branch

• Can be registered at a particular file system path (directory is created).
• Once registered, it can be updated, repaired, moved and uninstalled.
• It is treated as installed if either the last update or repair task succeeds.
• Once installed, the Process can be started.

App Branch Task

• Represents a long-running operation.
• Can be started, making it ongoing.
• If ongoing, in some cases it can be canceled (at the moment only Update and Repair Tasks are cancellable).
• Once completed, it is treated as finished.

Window

• There is only one window.
• If hidden, the theme continues to execute in the background.

Protocol Requests (aka "deeplinks")

• Once the runtime receives such a request, it is treated as pending.
• If pending, it can be dismissed.

Changelog

[1.1.1]

Changed

• Documentation improvements

[1.1.0]

Added

• Documentation for Preset type in patchkit-launcher-runtime-package-dev-tools-base
• Support for Windows code certificates with a custom file signing function (WindowsCustomCodeCertificatePreset type in patchkit-launcher-runtime-package-dev-tools-base)

Changed

• Building will now crash if macOS code signing is enabled but Apple Team ID is not provided (so notarization cannot be performed)

Fixed

• Disable default auto-discovery of macOS code certificates and force using the one specified in the preset

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.