Desktop open capabilities

Overview

App capability calls are a standardized set of desktop-level APIs on UGOS. Apps invoke them in a uniform way for files, task center, system info, UI interactions, and more.

Module

• Module: cloudWindow (from ugos-core)

Highlights

• Uniform API: Promise-based calls
• Type safety: Full TypeScript typings
• Errors: Consistent error handling
• Cross-app: Shared capabilities across apps

Basic usage

Import

import cloudWindow from '@ugreen-nas/core/cloudWindow'

Typical call

cloudWindow.useCapacity('capacityName', {
    // parameters required by the capability
}).then((result) => {
    console.log('OK:', result)
}).catch((error) => {
    console.error('Failed:', error)
})

async / await

async function callCapacity() {
    try {
        const result = await cloudWindow.useCapacity('capacityName', {
            // params
        })
        console.log('OK:', result)
    } catch (error) {
        console.error('Failed:', error)
    }
}

Errors

Calling a non-existent capability returns a standard error:

cloudWindow.useCapacity('nonExistentCapacity')
    .catch((error) => {
        // e.g. "xxxx not found"
        console.error(error.message)
    })

Basics

openApp

Open an app or URL by appId (including Docker apps).

Parameters: options (data), fields:

Name	Type	Required	Description
appId	string	Yes	Application ID
data	any	No	Data passed to the app. If data.routerParamsPath is a string, it is appended to the window URL
config	cloudWindowConfig	No	Window options — see Window configuration
noAssembly	boolean	No	4th arg to WindowServer.wake; controls data wrapping

Returns: Resolved/rejected WindowServer.wake promise.

addApiEncryptIgnore

Add uglink multi-channel paths to the payload-encryption ignore list.

Parameters: string[] — API path list

Returns: boolean — false if already in the list

openAppCenterDetail

Open App Center manage/detail (WindowServer.wakeToAppCenterManage).

Parameters:

Name	Type	Required	Description
appId	string	No	Defaults to caller app ID
appCenterType	—	Yes	Type enum aligned with desktop

Returns: wakeToAppCenterManage promise outcome

Tokens

getThirdToken

Third-party token and display-related user settings.

Parameters: none

Returns: object fields:

Field	Description
dateFormat	User date format
timeFormat	User time format
temperatureUnit	Temperature unit
third_token	Configured third_token
lang	Current i18n.locale

Example:

await cloudWindow.useCapacity('getThirdToken')

Files

getLocalPath

List subdirectories under a local path.

Parameters: directory path (string)

Returns: subdirectory list

openLocalPath

Open a local path.

Parameters:

Name	Type	Required	Description
path	string	Yes	Local path
openType	'openPath' | 'showFile'	Yes	'openPath' opens; 'showFile' reveals in file manager

You may also pass only a path string (omit openType).

Returns: boolean — success

System info

getComputerUserFolder

Current user home folder on the local machine.

Parameters: none

Returns: path (string)

getComputerName

Computer name.

Parameters: none

Returns: name (string)

getDeviceLocation

Device location.

Parameters: none

Returns: location (string), default 'China'

checkComputerPathExists

Whether a path exists.

Parameters:

Name	Type	Required	Description
path	string	Yes	Path to check

Returns: boolean

Examples

Open another app with data

import { AppCapacity } from 'ugos-pro-types/capacity'

async function openFileManager(path: string) {
  try {
    const result = await cloudWindow.useCapacity('openApp', {
      appId: 'com.ugreen.filemgr',
      data: { path }
    })
    console.log('File manager opened')
  } catch (error) {
    console.error('Open failed:', error)
  }
}

Fetch token

async function fetchNasData(endpoint: string) {
  try {
    const token = await cloudWindow.useCapacity('getThirdToken')
  } catch (error) {
    console.error('Failed:', error)
    throw error
  }
}

Notes

1. Permissions: Some capabilities need explicit permission.
2. Errors: Prefer try/catch or .catch().
3. Timeout: Optional third argument for timeouts.
4. Types: Use TypeScript and official typings where possible.
5. Platform: Some capabilities are Windows/Mac only.
6. Version: Newer capabilities may require specific client/firmware.