@sigma-file-manager/api 1.3.0 → 1.5.0

package/README.md

@@ -27,6 +27,16 @@ async function activate(context) {
 }
 ```
 
+Bundled English defaults with locale JSON from `mergeFromPath`:
+
+```js
+import { extensionMessages } from './messages.js';
+
+export const t = sigma.i18n.createExtensionTranslator(extensionMessages);
+```
+
+`formatMessage` for `{placeholder}` strings is available as `sigma.i18n.formatMessage` when needed.
+
 ## Manifest schema
 
 Use this schema URL in your extension `package.json`:
@@ -39,6 +49,4 @@ Use this schema URL in your extension `package.json`:
 
 ## Release
 
-- Package versions are independent from app versions.
-- Use `api-vX.Y.Z` tags for package releases.
-- Publish from `packages/api` with `npm publish`.
+API package versions are independent from app versions and tagged as `api-vX.Y.Z`.

package/index.d.ts

@@ -13,7 +13,9 @@ export type ExtensionPermission
     | 'fs.write'
     | 'notifications'
     | 'dialogs'
-    | 'shell';
+    | 'shell'
+    | 'clipboard'
+    | 'openUrl';
 
 export type ExtensionActivationEvent
   = | 'onStartup'
@@ -22,6 +24,7 @@ export type ExtensionActivationEvent
     | 'onEnable'
     | 'onDisable'
     | 'onUpdate'
+    | 'onLocaleChange'
     | `onCommand:${string}`;
 
 export interface ExtensionPublisher {
@@ -125,7 +128,26 @@ export interface ExtensionEngines {
 }
 
 export type PlatformOS = 'windows' | 'macos' | 'linux';
-export type PlatformArch = 'x64' | 'arm64' | 'x86';
+export type PlatformArch = 'x64' | 'arm64';
+
+export interface ManifestBinaryAsset {
+  platform: PlatformOS;
+  arch?: PlatformArch[];
+  downloadUrl: string;
+  integrity: string;
+  archive?: boolean;
+  executable?: string;
+}
+
+export interface ManifestBinaryDefinition {
+  id: string;
+  name: string;
+  version: string;
+  executable?: string;
+  repository?: string;
+  platforms?: PlatformOS[];
+  assets: ManifestBinaryAsset[];
+}
 
 export interface ExtensionManifest {
   id: string;
@@ -145,6 +167,7 @@ export interface ExtensionManifest {
   activationEvents?: ExtensionActivationEvent[];
   contributes?: ExtensionContributions;
   platforms?: PlatformOS[];
+  binaries?: ManifestBinaryDefinition[];
   engines: ExtensionEngines;
 }
 
@@ -258,21 +281,13 @@ export interface SaveFileDialogOptions {
   filters?: FileDialogFilter[];
 }
 
-export interface BinaryInstallOptions {
-  name: string;
-  downloadUrl: string | ((platform: PlatformOS) => string);
-  integrity?: string;
-  executable?: string;
-  version?: string;
-  repository?: string;
-}
-
 export interface BinaryInfo {
   id: string;
   path: string;
   version?: string;
   storageVersion?: string | null;
   repository?: string;
+  downloadUrl?: string;
   latestVersion?: string;
   hasUpdate?: boolean;
   latestCheckedAt?: number;
@@ -339,6 +354,7 @@ export interface ModalHandle {
   close(): void;
   updateElement(id: string, updates: Partial<UIElement>): void;
   setContent(content: UIElement[]): void;
+  setButtons(buttons: ModalButton[]): void;
   getValues(): Record<string, unknown>;
 }
 
@@ -348,7 +364,7 @@ export interface ToolbarRenderHandle {
 
 export interface PlatformInfo {
   os: PlatformOS;
-  arch: PlatformArch;
+  arch: string;
   pathSeparator: string;
   isWindows: boolean;
   isMacos: boolean;
@@ -360,7 +376,11 @@ export interface SigmaExtensionAPI {
     t(key: string, params?: Record<string, string | number>): string;
     mergeMessages(messages: Record<string, Record<string, string>>): void;
     mergeFromPath(basePath: string): Promise<void>;
-    extensionT(key: string, params?: Record<string, string | number>): string;
+    extensionT(key: string, params?: Record<string, string | number>, fallback?: string): string;
+    formatMessage(template: string, params?: Record<string, string | number>): string;
+    createExtensionTranslator(
+      messages: Record<string, string>,
+    ): (key: string, params?: Record<string, string | number>) => string;
   };
   contextMenu: {
     registerItem(
@@ -437,11 +457,20 @@ export interface SigmaExtensionAPI {
   ui: {
     showNotification(options: NotificationOptions): void;
     showDialog(options: DialogOptions): Promise<DialogResult>;
+    copyText(text: string): Promise<void>;
+    /**
+     * Writes data to the clipboard. Supported MIME types: `image/png`, `text/html`, `text/plain`.
+     * When `text/html` is provided alongside `text/plain`, the plain text is used as fallback.
+     * Writes the first supported representation found across items (image/png > text/html > text/plain).
+     * Throws if only unsupported types are provided.
+     */
+    clipboardWrite(items: Record<string, Uint8Array>[]): Promise<void>;
     withProgress<T>(
       options: ProgressOptions,
       task: (progress: Progress, token: CancellationToken) => Promise<T>
     ): Promise<T>;
     createModal(options: ModalOptions): ModalHandle;
+    showModal(options: ModalOptions): Promise<Record<string, unknown> | null>;
     input(options: {
       id: string;
       label?: string;
@@ -553,18 +582,24 @@ export interface SigmaExtensionAPI {
   };
   platform: {
     readonly os: PlatformOS;
-    readonly arch: PlatformArch;
+    readonly arch: string;
     readonly pathSeparator: string;
     readonly isWindows: boolean;
     readonly isMacos: boolean;
     readonly isLinux: boolean;
     joinPath(...segments: string[]): string;
   };
+  path: {
+    dirname(filePath: string): string;
+    basename(filePath: string, suffix?: string): string;
+    extname(filePath: string): string;
+  };
+  runtime: {
+    isExtensionInstallCancelledError(error: unknown): boolean;
+  };
   binary: {
-    ensureInstalled(id: string, options: BinaryInstallOptions): Promise<string>;
     getPath(id: string): Promise<string | null>;
     isInstalled(id: string): Promise<boolean>;
-    remove(id: string): Promise<void>;
     getInfo(id: string): Promise<BinaryInfo | null>;
   };
 }

package/manifest.schema.json

@@ -129,7 +129,9 @@
           "fs.write",
           "notifications",
           "dialogs",
-          "shell"
+          "shell",
+          "clipboard",
+          "openUrl"
         ]
       }
     },
@@ -146,7 +148,8 @@
               "onUninstall",
               "onEnable",
               "onDisable",
-              "onUpdate"
+              "onUpdate",
+              "onLocaleChange"
             ]
           },
           {
@@ -168,11 +171,21 @@
               "title"
             ],
             "properties": {
-              "id": { "type": "string" },
-              "title": { "type": "string" },
-              "description": { "type": "string" },
-              "icon": { "type": "string" },
-              "shortcut": { "type": "string" }
+              "id": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "icon": {
+                "type": "string"
+              },
+              "shortcut": {
+                "type": "string"
+              }
             }
           }
         },
@@ -185,11 +198,21 @@
               "title"
             ],
             "properties": {
-              "id": { "type": "string" },
-              "title": { "type": "string" },
-              "icon": { "type": "string" },
-              "group": { "type": "string" },
-              "order": { "type": "number" },
+              "id": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "icon": {
+                "type": "string"
+              },
+              "group": {
+                "type": "string"
+              },
+              "order": {
+                "type": "number"
+              },
               "when": {
                 "type": "object",
                 "properties": {
@@ -230,10 +253,18 @@
               "icon"
             ],
             "properties": {
-              "id": { "type": "string" },
-              "title": { "type": "string" },
-              "icon": { "type": "string" },
-              "order": { "type": "number" },
+              "id": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "icon": {
+                "type": "string"
+              },
+              "order": {
+                "type": "number"
+              },
               "url": {
                 "type": "string",
                 "format": "uri"
@@ -251,9 +282,15 @@
               "items"
             ],
             "properties": {
-              "id": { "type": "string" },
-              "title": { "type": "string" },
-              "icon": { "type": "string" },
+              "id": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "icon": {
+                "type": "string"
+              },
               "items": {
                 "type": "array",
                 "items": {
@@ -263,11 +300,21 @@
                     "title"
                   ],
                   "properties": {
-                    "id": { "type": "string" },
-                    "title": { "type": "string" },
-                    "icon": { "type": "string" },
-                    "commandId": { "type": "string" },
-                    "separator": { "type": "boolean" }
+                    "id": {
+                      "type": "string"
+                    },
+                    "title": {
+                      "type": "string"
+                    },
+                    "icon": {
+                      "type": "string"
+                    },
+                    "commandId": {
+                      "type": "string"
+                    },
+                    "separator": {
+                      "type": "boolean"
+                    }
                   }
                 }
               }
@@ -357,8 +404,12 @@
               "key"
             ],
             "properties": {
-              "command": { "type": "string" },
-              "key": { "type": "string" },
+              "command": {
+                "type": "string"
+              },
+              "key": {
+                "type": "string"
+              },
               "when": {
                 "type": "string",
                 "enum": [
@@ -389,6 +440,104 @@
       "minItems": 1,
       "uniqueItems": true
     },
+    "binaries": {
+      "type": "array",
+      "description": "Binary definitions installed and managed by the host application",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "version",
+          "assets"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique binary identifier shared across extensions"
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name of the binary"
+          },
+          "version": {
+            "type": "string",
+            "description": "Pinned binary version used for shared lookup and install",
+            "minLength": 1
+          },
+          "executable": {
+            "type": "string",
+            "description": "Relative path to the executable inside the extracted directory"
+          },
+          "repository": {
+            "type": "string",
+            "format": "uri",
+            "description": "Upstream repository URL for reference"
+          },
+          "platforms": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "windows",
+                "macos",
+                "linux"
+              ]
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "assets": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": [
+                "platform",
+                "downloadUrl",
+                "integrity"
+              ],
+              "properties": {
+                "platform": {
+                  "type": "string",
+                  "enum": [
+                    "windows",
+                    "macos",
+                    "linux"
+                  ]
+                },
+                "arch": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": [
+                      "x64",
+                      "arm64"
+                    ]
+                  },
+                  "minItems": 1,
+                  "uniqueItems": true
+                },
+                "downloadUrl": {
+                  "type": "string",
+                  "format": "uri"
+                },
+                "integrity": {
+                  "type": "string",
+                  "pattern": "^sha256:[a-fA-F0-9]{64}$"
+                },
+                "archive": {
+                  "type": "boolean"
+                },
+                "executable": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "engines": {
       "type": "object",
       "description": "Version constraints",
@@ -403,4 +552,4 @@
       }
     }
   }
-}
+}

package/package.json

@@ -1,20 +1,20 @@
-{
-  "name": "@sigma-file-manager/api",
-  "version": "1.3.0",
-  "description": "Type definitions and manifest schema for Sigma File Manager extensions",
-  "license": "GPL-3.0-or-later",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aleksey-hoffman/sigma-file-manager.git",
-    "directory": "packages/api"
-  },
-  "files": [
-    "index.d.ts",
-    "manifest.schema.json",
-    "README.md"
-  ],
-  "types": "index.d.ts",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@sigma-file-manager/api",
+  "version": "1.5.0",
+  "description": "Type definitions and manifest schema for Sigma File Manager extensions",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aleksey-hoffman/sigma-file-manager.git",
+    "directory": "packages/api"
+  },
+  "files": [
+    "index.d.ts",
+    "manifest.schema.json",
+    "README.md"
+  ],
+  "types": "index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}