@blastlauncher/protocol 0.0.0-stage → 3.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Yukai Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @blastlauncher/protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Blast's protocol package.
+Emitted ESM and TypeScript declarations for Node.js 24.20+.
+See https://github.com/BlastLauncher/blast for documentation.

package/dist/capabilities.d.ts

@@ -0,0 +1,584 @@
+/** `"session"` when the engine answers the capability itself, else `"grant"`. */
+export type CapabilityScope = "session" | "grant";
+export type CapabilitySchemaType = "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+/**
+ * The small JSON-Schema subset this catalog uses. It describes the wire shapes
+ * for embedders without pulling a schema library into the dependency-free
+ * protocol package.
+ */
+export interface CapabilitySchema {
+    readonly type?: CapabilitySchemaType | readonly CapabilitySchemaType[];
+    readonly properties?: Readonly<Record<string, CapabilitySchema>>;
+    readonly required?: readonly string[];
+    readonly items?: CapabilitySchema;
+    readonly enum?: readonly (string | number | boolean | null)[];
+}
+export interface CapabilitySpec {
+    readonly scope: CapabilityScope;
+    /** One line describing what the capability does. */
+    readonly summary: string;
+    readonly params: CapabilitySchema;
+    readonly result: CapabilitySchema;
+    /** `@raycast/api` symbol paths that trigger the request. */
+    readonly api: readonly string[];
+}
+/**
+ * Every capability the runtime can request, keyed by wire name. Params and
+ * results are the shapes the runtime sends and accepts, not the full Raycast
+ * API types.
+ */
+export declare const CAPABILITIES: {
+    readonly "storage.get": {
+        readonly scope: "session";
+        readonly summary: "Reads a LocalStorage or internal storage key.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly key: CapabilitySchema;
+                readonly scope: {
+                    readonly type: "string";
+                    readonly enum: readonly ["blast:internal"];
+                };
+            };
+            readonly required: readonly ["key"];
+        };
+        readonly result: {
+            readonly type: readonly ["string", "number", "boolean", "null"];
+        };
+        readonly api: readonly ["LocalStorage.getItem", "getLocalStorageItem", "Form.TextField.Props.storeValue", "Form.Dropdown.Props.storeValue", "List.Dropdown.Props.storeValue", "Grid.Dropdown.Props.storeValue"];
+    };
+    readonly "storage.set": {
+        readonly scope: "session";
+        readonly summary: "Writes a LocalStorage or internal storage key.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly key: CapabilitySchema;
+                readonly value: {
+                    readonly type: readonly ["string", "number", "boolean"];
+                };
+                readonly scope: {
+                    readonly type: "string";
+                    readonly enum: readonly ["blast:internal"];
+                };
+            };
+            readonly required: readonly ["key", "value"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["LocalStorage.setItem", "setLocalStorageItem", "Form.TextField.Props.storeValue", "Form.Dropdown.Props.storeValue", "List.Dropdown.Props.storeValue", "Grid.Dropdown.Props.storeValue"];
+    };
+    readonly "storage.remove": {
+        readonly scope: "session";
+        readonly summary: "Removes a LocalStorage, internal storage or form draft key.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly key: CapabilitySchema;
+                readonly scope: {
+                    readonly type: "string";
+                    readonly enum: readonly ["blast:internal"];
+                };
+            };
+            readonly required: readonly ["key"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["LocalStorage.removeItem", "removeLocalStorageItem", "Form.TextField.Props.storeValue", "Form.Dropdown.Props.storeValue", "List.Dropdown.Props.storeValue", "Grid.Dropdown.Props.storeValue"];
+    };
+    readonly "storage.all": {
+        readonly scope: "session";
+        readonly summary: "Reads every LocalStorage entry for the extension.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["LocalStorage.allItems", "allLocalStorageItems"];
+    };
+    readonly "storage.clear": {
+        readonly scope: "session";
+        readonly summary: "Clears every LocalStorage entry for the extension.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["LocalStorage.clear", "clearLocalStorage"];
+    };
+    readonly "oauth.tokens.get": {
+        readonly scope: "session";
+        readonly summary: "Reads the stored OAuth token set for a provider.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly providerId: CapabilitySchema;
+            };
+            readonly required: readonly ["providerId"];
+        };
+        readonly result: {
+            readonly type: readonly ["object", "null"];
+            readonly properties: {
+                readonly accessToken: CapabilitySchema;
+                readonly refreshToken: CapabilitySchema;
+                readonly idToken: CapabilitySchema;
+                readonly expiresIn: CapabilitySchema;
+                readonly scope: {
+                    readonly type: readonly ["string", "array"];
+                    readonly items: CapabilitySchema;
+                };
+                readonly revocationEndpoint: CapabilitySchema;
+            };
+        };
+        readonly api: readonly ["OAuth.PKCEClient.getTokens"];
+    };
+    readonly "oauth.tokens.set": {
+        readonly scope: "session";
+        readonly summary: "Stores an OAuth token set for a provider.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly providerId: CapabilitySchema;
+                readonly tokens: CapabilitySchema;
+            };
+            readonly required: readonly ["providerId", "tokens"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["OAuth.PKCEClient.setTokens"];
+    };
+    readonly "oauth.tokens.remove": {
+        readonly scope: "session";
+        readonly summary: "Removes the stored OAuth token set for a provider.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly providerId: CapabilitySchema;
+            };
+            readonly required: readonly ["providerId"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["OAuth.PKCEClient.removeTokens"];
+    };
+    readonly "oauth.authorize": {
+        readonly scope: "grant";
+        readonly summary: "Asks the client to run an OAuth authorization flow and return a code.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly url: CapabilitySchema;
+                readonly providerName: CapabilitySchema;
+                readonly providerId: CapabilitySchema;
+                readonly redirectMethod: {
+                    readonly type: "string";
+                };
+                readonly providerIcon: CapabilitySchema;
+                readonly description: CapabilitySchema;
+            };
+            readonly required: readonly ["url", "providerName", "providerId", "redirectMethod"];
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly authorizationCode: CapabilitySchema;
+            };
+            readonly required: readonly ["authorizationCode"];
+        };
+        readonly api: readonly ["OAuth.PKCEClient.authorize"];
+    };
+    readonly "ai.ask": {
+        readonly scope: "grant";
+        readonly summary: "Asks an AI model for text; own-provider `{ id }` models are answered by the engine.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly prompt: CapabilitySchema;
+                readonly model: {
+                    readonly type: readonly ["string", "object"];
+                    readonly properties: {
+                        readonly id: CapabilitySchema;
+                    };
+                };
+                readonly creativity: {
+                    readonly type: readonly ["string", "number"];
+                };
+            };
+            readonly required: readonly ["prompt"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["AI.ask"];
+    };
+    readonly "ai.models.refresh": {
+        readonly scope: "session";
+        readonly summary: "Re-lists the extension's own AI provider models.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["AI.refreshModels"];
+    };
+    readonly "ai.decide": {
+        readonly scope: "grant";
+        readonly summary: "Asks a client for typed answers to experimental decision questions.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly state: CapabilitySchema;
+                readonly questions: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly type: {
+                            readonly type: "string";
+                            readonly enum: readonly ["noul", "score", "choice"];
+                        };
+                        readonly instructions: CapabilitySchema;
+                        readonly criteria: {
+                            readonly type: readonly ["array", "object"];
+                        };
+                    };
+                    readonly required: readonly ["type", "instructions"];
+                };
+            };
+            readonly required: readonly ["state", "questions"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["AI.experimental_decide"];
+    };
+    readonly "browser.tabs": {
+        readonly scope: "grant";
+        readonly summary: "Lists the browser tabs a client chooses to expose.";
+        readonly params: CapabilitySchema;
+        readonly result: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: CapabilitySchema;
+                    readonly url: CapabilitySchema;
+                    readonly title: CapabilitySchema;
+                    readonly favicon: CapabilitySchema;
+                    readonly active: CapabilitySchema;
+                };
+                readonly required: readonly ["id", "url", "active"];
+            };
+        };
+        readonly api: readonly ["BrowserExtension.getTabs"];
+    };
+    readonly "browser.content": {
+        readonly scope: "grant";
+        readonly summary: "Returns the content of a browser tab.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly cssSelector: CapabilitySchema;
+                readonly tabId: CapabilitySchema;
+                readonly format: {
+                    readonly type: "string";
+                    readonly enum: readonly ["html", "text", "markdown"];
+                };
+            };
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["BrowserExtension.getContent"];
+    };
+    readonly "clipboard.copy": {
+        readonly scope: "grant";
+        readonly summary: "Copies text, HTML or a file path to the clipboard.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["Clipboard.copy", "Action.CopyToClipboard", "ActionPanel.Item.CopyToClipboard"];
+    };
+    readonly "clipboard.clear": {
+        readonly scope: "grant";
+        readonly summary: "Clears the clipboard.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["Clipboard.clear"];
+    };
+    readonly "clipboard.paste": {
+        readonly scope: "grant";
+        readonly summary: "Pastes text, HTML or a file path into the frontmost application.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["Clipboard.paste", "Action.Paste", "ActionPanel.Item.Paste"];
+    };
+    readonly "clipboard.read": {
+        readonly scope: "grant";
+        readonly summary: "Reads the clipboard, optionally at a history offset.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly offset: {
+                    readonly type: "integer";
+                    readonly enum: readonly [0, 1, 2, 3, 4, 5];
+                };
+            };
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly text: CapabilitySchema;
+                readonly file: CapabilitySchema;
+                readonly html: CapabilitySchema;
+            };
+            readonly required: readonly ["text"];
+        };
+        readonly api: readonly ["Clipboard.read", "Clipboard.readText"];
+    };
+    readonly "open.url": {
+        readonly scope: "grant";
+        readonly summary: "Opens an HTTP(S) URL, optionally with a named application.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly url: CapabilitySchema;
+                readonly application: {
+                    readonly type: readonly ["string", "object"];
+                };
+            };
+            readonly required: readonly ["url"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["open", "Action.Open", "Action.OpenWith", "Action.OpenInBrowser"];
+    };
+    readonly "open.path": {
+        readonly scope: "grant";
+        readonly summary: "Opens a file or folder, optionally with a named application.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly path: CapabilitySchema;
+                readonly application: {
+                    readonly type: readonly ["string", "object"];
+                };
+            };
+            readonly required: readonly ["path"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["open", "Action.Open", "Action.OpenWith"];
+    };
+    readonly "selection.text": {
+        readonly scope: "grant";
+        readonly summary: "Returns the selected text; an empty string means nothing is selected.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["getSelectedText"];
+    };
+    readonly "selection.files": {
+        readonly scope: "grant";
+        readonly summary: "Returns the selected file-system items.";
+        readonly params: CapabilitySchema;
+        readonly result: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly path: CapabilitySchema;
+                };
+            };
+        };
+        readonly api: readonly ["getSelectedFinderItems"];
+    };
+    readonly "applications.frontmost": {
+        readonly scope: "grant";
+        readonly summary: "Returns the frontmost application.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["getFrontmostApplication"];
+    };
+    readonly "applications.list": {
+        readonly scope: "grant";
+        readonly summary: "Lists installed applications, optionally filtered by path.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly path: CapabilitySchema;
+            };
+        };
+        readonly result: {
+            readonly type: "array";
+            readonly items: CapabilitySchema;
+        };
+        readonly api: readonly ["getApplications"];
+    };
+    readonly "applications.default": {
+        readonly scope: "grant";
+        readonly summary: "Returns the application the machine would open a path with.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly path: CapabilitySchema;
+            };
+            readonly required: readonly ["path"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["getDefaultApplication"];
+    };
+    readonly "finder.show": {
+        readonly scope: "grant";
+        readonly summary: "Reveals a file or folder in the file manager.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly path: CapabilitySchema;
+            };
+            readonly required: readonly ["path"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["showInFinder", "Action.ShowInFinder"];
+    };
+    readonly trash: {
+        readonly scope: "grant";
+        readonly summary: "Moves files or folders to the trash.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly paths: CapabilitySchema;
+            };
+            readonly required: readonly ["paths"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["trash", "Action.Trash"];
+    };
+    readonly "window.desktops": {
+        readonly scope: "grant";
+        readonly summary: "Lists desktops across all screens.";
+        readonly params: CapabilitySchema;
+        readonly result: {
+            readonly type: "array";
+            readonly items: CapabilitySchema;
+        };
+        readonly api: readonly ["WindowManagement.getDesktops"];
+    };
+    readonly "window.active": {
+        readonly scope: "grant";
+        readonly summary: "Returns the active window.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["WindowManagement.getActiveWindow"];
+    };
+    readonly "window.list": {
+        readonly scope: "grant";
+        readonly summary: "Lists the windows on the active desktop.";
+        readonly params: CapabilitySchema;
+        readonly result: {
+            readonly type: "array";
+            readonly items: CapabilitySchema;
+        };
+        readonly api: readonly ["WindowManagement.getWindowsOnActiveDesktop"];
+    };
+    readonly "window.setBounds": {
+        readonly scope: "grant";
+        readonly summary: "Moves, resizes or makes a window fullscreen.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly id: CapabilitySchema;
+                readonly bounds: {
+                    readonly type: readonly ["object", "string"];
+                };
+                readonly desktopId: CapabilitySchema;
+            };
+            readonly required: readonly ["id", "bounds"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["WindowManagement.setWindowBounds"];
+    };
+    readonly "preferences.open": {
+        readonly scope: "grant";
+        readonly summary: "Asks the client to open extension or command preferences.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly scope: {
+                    readonly type: "string";
+                    readonly enum: readonly ["extension", "command"];
+                };
+            };
+            readonly required: readonly ["scope"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["openExtensionPreferences", "openCommandPreferences"];
+    };
+    readonly "command.launch": {
+        readonly scope: "grant";
+        readonly summary: "Launches another command, passing arguments and launch context.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly name: CapabilitySchema;
+                readonly type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["userInitiated", "background"];
+                };
+                readonly extensionName: CapabilitySchema;
+                readonly ownerOrAuthorName: CapabilitySchema;
+                readonly arguments: CapabilitySchema;
+                readonly context: CapabilitySchema;
+                readonly fallbackText: CapabilitySchema;
+            };
+            readonly required: readonly ["name", "type"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["launchCommand"];
+    };
+    readonly "command.metadata": {
+        readonly scope: "grant";
+        readonly summary: "Updates the command's subtitle in the client.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly subtitle: {
+                    readonly type: readonly ["string", "null"];
+                };
+            };
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["updateCommandMetadata"];
+    };
+    readonly "snippet.create": {
+        readonly scope: "grant";
+        readonly summary: "Creates a snippet from text, a name and a keyword.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly text: CapabilitySchema;
+                readonly name: CapabilitySchema;
+                readonly keyword: CapabilitySchema;
+            };
+            readonly required: readonly ["text"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["Action.CreateSnippet"];
+    };
+    readonly "quicklink.create": {
+        readonly scope: "grant";
+        readonly summary: "Creates a quicklink from a link and optional metadata.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly link: CapabilitySchema;
+                readonly name: CapabilitySchema;
+                readonly icon: CapabilitySchema;
+                readonly application: {
+                    readonly type: readonly ["string", "object"];
+                };
+            };
+            readonly required: readonly ["link"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["Action.CreateQuicklink"];
+    };
+    readonly "quicklook.toggle": {
+        readonly scope: "grant";
+        readonly summary: "Toggles Quick Look for the client's selected item.";
+        readonly params: CapabilitySchema;
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["Action.ToggleQuickLook"];
+    };
+    readonly "mcp.install": {
+        readonly scope: "grant";
+        readonly summary: "Installs an MCP server descriptor.";
+        readonly params: {
+            readonly type: "object";
+            readonly properties: {
+                readonly server: CapabilitySchema;
+            };
+            readonly required: readonly ["server"];
+        };
+        readonly result: CapabilitySchema;
+        readonly api: readonly ["Action.InstallMCPServer"];
+    };
+};
+export type CapabilityName = keyof typeof CAPABILITIES;
+/** Whether a wire name names a capability in `CAPABILITIES`. */
+export declare function isCapabilityName(name: string): name is CapabilityName;