Background SwiftBiu API

Standard Actions and Web App launchers run in the background script.js sandbox. This environment injects the global SwiftBiu object and its lowercase alias swiftBiu.

Environment and Configuration

• SwiftBiu.isSandboxed: Boolean, whether the app is running inside macOS App Sandbox.
• SwiftBiu.getConfig(key: String): synchronously reads a configuration value as a string.
• SwiftBiu.setConfig(key: String, value: String): persists a configuration value.
• SwiftBiu.screenSize: helps calculate initial Web UI size and position.

Clipboard and Text

• SwiftBiu.writeToClipboard(text: String): writes text to the system clipboard. Requires clipboardWrite.
• SwiftBiu.copyText(text: String): compatible copy helper.
• SwiftBiu.getClipboard(): returns plain text from the clipboard. Requires clipboardRead.
• SwiftBiu.pasteText(text: String): copies and pastes into the previously active window. Requires paste.

Local File Reads and Metadata

• SwiftBiu.getFileMetadata(path: String): returns size, timestamps, and content type. Requires localFileRead.
• SwiftBiu.readLocalFile(path: String): reads a selected file and returns Base64. Requires localFileRead.
• SwiftBiu.readLocalTextFile(path: String): decodes a selected file as UTF-8. Requires localFileRead.
• SwiftBiu.listDirectory(path: String): lists direct children and metadata. Requires localFileRead.
• SwiftBiu.fileExists(path: String): checks whether a path exists as a file. Requires localFileRead or localFileWrite.
• SwiftBiu.directoryExists(path: String): checks whether a path exists as a directory. Requires localFileRead or localFileWrite.

File and Folder Authorization

• SwiftBiu.pickLocalFile(options?: Object): opens the native file picker, persists authorization, and returns the selected path. Supports kind: "application", kind: "image", and allowedExtensions. Requires localFileRead or localFileWrite.
• SwiftBiu.pickLocalDirectory(): opens the native folder picker, persists authorization, and returns the folder path. Requires localFileWrite.
• SwiftBiu.requestDirectoryAuthorization(path: String): asks the user to authorize a folder covering the target path. Requires localFileWrite.
• SwiftBiu.hasAuthorizedDirectoryAccess(path: String): checks whether persisted authorization covers a path. Requires localFileWrite.

When access is missing, request authorization immediately. Stop cleanly when the user cancels instead of returning a false success state.

Local File Writes

• SwiftBiu.createLocalDirectory(path: String): creates a directory in an authorized location. Requires localFileWrite.
• SwiftBiu.createLocalFile(path: String, base64String: String): creates a file from Base64. Requires localFileWrite.
• SwiftBiu.writeLocalTextFile(path: String, text: String): creates a UTF-8 text file. Requires localFileWrite.
• SwiftBiu.overwriteLocalFile(path: String, base64String: String): replaces an accessible file. Requires localFileWrite.
• SwiftBiu.renameLocalFile(path: String, newName: String): renames a file in place. Requires localFileWrite.
• SwiftBiu.copyLocalFile(sourcePath: String, destinationPath: String): copies a file. Requires localFileWrite.
• SwiftBiu.moveLocalFile(sourcePath: String, destinationPath: String): moves a file. Requires localFileWrite.
• SwiftBiu.trashLocalItem(path: String): moves an item to the macOS Trash. Requires localFileWrite.

File Icons

• SwiftBiu.extractFileIcon(path: String, options?: Object): extracts a file or app icon through the native host. Success returns { success, base64, fileName, width, height, format }; failure returns { success: false, error }. Requires localFileRead.
• SwiftBiu.setFileIcon(targetPath: String, iconPath: String, options?: Object): applies a custom Finder icon to a file, folder, or .app. Requires localFileRead and localFileWrite.

For App Store compatibility, use these host APIs instead of shell, AppleScript, sips, qlmanage, or osascript.

Opening Resources

• SwiftBiu.openURL(urlString: String): opens a link in the default browser.
• SwiftBiu.openFileInPreview(filePath: String): opens a file in the default macOS app.
• SwiftBiu.openFileWithApp(filePath: String, appBundleID: String): opens a file with a specific app and returns Boolean. Requires localFileRead.

Notifications, Images, and Loading

• SwiftBiu.showNotification(title: String, body: String): sends a system notification. Requires notifications.
• SwiftBiu.showImage(imageSource: String, position?: Object, context?: Object): displays a native image toast from Base64 or an http/https URL. Requires notifications.
• SwiftBiu.showInteractiveImage(options, onRegenerate): creates an interactive image session and returns sessionID. Requires notifications.
• SwiftBiu.updateInteractiveImage(sessionID, options): updates an image session.
• SwiftBiu.failInteractiveImage(sessionID, message): fails an image session.
• SwiftBiu.showLoadingIndicator(position: Object): shows a native loading indicator.
• SwiftBiu.hideLoadingIndicator(): hides it.

Use the loading indicator only for lightweight actions without their own interface. Web UIs, AI bubbles, and image sessions should manage loading inside their own lifecycle.

Network Requests

• SwiftBiu.fetch(url, options, onSuccess, onError): callback-based request. Requires network.
• SwiftBiu.fetchStream(url, options, onEvent, onError): starts a stream and returns streamID. Requires network.
• SwiftBiu.cancelFetchStream(streamID: String): cancels an active stream.

Shell Scripts

• SwiftBiu.runShellScript(script, context): synchronously executes Bash or Zsh. Requires runShellScript.

Related Documentation

• Manifest and Action Types
• Configuration
• Permissions
• Native Workflows
• Web UI API
• Cross-Platform Compatibility