@blastlauncher/runtime 1.0.1 → 3.0.0-alpha.0

package/dist/api/oauth.d.ts

@@ -0,0 +1,84 @@
+import type { JsonValue } from "../reconciler/index.js";
+import { OAuth as enums } from "./enums.generated.js";
+export type RedirectMethod = (typeof enums.RedirectMethod)[keyof typeof enums.RedirectMethod];
+export type PKCEClientOptions = {
+    redirectMethod: RedirectMethod;
+    providerName: string;
+    providerIcon?: JsonValue;
+    providerId?: string;
+    description?: string;
+    revocationEndpoint?: string;
+};
+export type AuthorizationRequestOptions = {
+    endpoint: string;
+    clientId: string;
+    scope: string;
+    extraParameters?: Record<string, string>;
+};
+export type ClientIdMetadataDocumentAuthorizationRequestOptions = Omit<AuthorizationRequestOptions, "clientId"> & {
+    clientId?: string;
+};
+export type AuthorizationRequestURLParams = {
+    clientId?: string;
+    codeChallenge: string;
+    codeVerifier: string;
+    state: string;
+    redirectURI: string;
+};
+export type AuthorizationRequest = AuthorizationRequestURLParams & {
+    clientId: string;
+    toURL(): string;
+};
+export type AuthorizationOptions = {
+    url: string;
+};
+export type AuthorizationResponse = {
+    authorizationCode: string;
+};
+export type TokenSetOptions = {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresIn?: number;
+    scope?: string | string[];
+};
+export type TokenResponse = {
+    access_token: string;
+    refresh_token?: string;
+    id_token?: string;
+    expires_in?: number;
+    scope?: string | string[];
+};
+export type TokenSet = Omit<TokenSetOptions, "scope"> & {
+    scope?: string;
+    updatedAt: Date;
+    isExpired(): boolean;
+};
+declare class PKCEClient<M extends RedirectMethod = RedirectMethod> {
+    redirectMethod: M;
+    providerName: string;
+    providerIcon?: JsonValue;
+    providerId: string;
+    description?: string;
+    revocationEndpoint?: string;
+    constructor(options: PKCEClientOptions & {
+        redirectMethod: M;
+    });
+    authorizationRequest(this: PKCEClient<"clientIdMetadataDocument">, options: ClientIdMetadataDocumentAuthorizationRequestOptions): Promise<AuthorizationRequest>;
+    authorizationRequest(options: AuthorizationRequestOptions): Promise<AuthorizationRequest>;
+    authorize(options: AuthorizationRequest | AuthorizationOptions): Promise<AuthorizationResponse>;
+    setTokens(options: TokenSetOptions | TokenResponse): Promise<void>;
+    getTokens(): Promise<TokenSet | undefined>;
+    removeTokens(): Promise<void>;
+}
+export declare const OAuth: {
+    RedirectMethod: {
+        readonly Web: "web";
+        readonly App: "app";
+        readonly AppURI: "appURI";
+        readonly ClientIdMetadataDocument: "clientIdMetadataDocument";
+    };
+    clientIdMetadataDocument: string;
+    PKCEClient: typeof PKCEClient;
+};
+export {};

package/dist/api/oauth.js

@@ -0,0 +1,125 @@
+import { createHash, randomBytes } from "node:crypto";
+import { requestCapability } from "./capability.js";
+import { OAuth as enums } from "./enums.generated.js";
+const clientIdMetadataDocument = "https://www.raycast.com/.well-known/oauth-client-metadata/raycast.json";
+const redirects = {
+    web: "https://raycast.com/redirect?packageName=Extension",
+    app: "raycast://oauth?package_name=Extension",
+    appURI: "com.raycast:/oauth?package_name=Extension",
+    clientIdMetadataDocument: "https://raycast.com/redirect?packageName=Extension",
+};
+class PKCEClient {
+    redirectMethod;
+    providerName;
+    providerIcon;
+    providerId;
+    description;
+    revocationEndpoint;
+    constructor(options) {
+        this.redirectMethod = options.redirectMethod;
+        this.providerName = options.providerName;
+        this.providerId = options.providerId ?? options.providerName;
+        if (options.providerIcon !== undefined)
+            this.providerIcon = options.providerIcon;
+        if (options.description !== undefined)
+            this.description = options.description;
+        if (options.revocationEndpoint !== undefined)
+            this.revocationEndpoint = options.revocationEndpoint;
+        if (!redirects[this.redirectMethod])
+            throw new TypeError("Unknown OAuth redirect method");
+    }
+    async authorizationRequest(options) {
+        const clientId = options.clientId ??
+            (this.redirectMethod === "clientIdMetadataDocument" ? clientIdMetadataDocument : undefined);
+        if (!clientId)
+            throw new TypeError("OAuth authorizationRequest requires a clientId");
+        const codeVerifier = randomBytes(32).toString("base64url");
+        const request = {
+            clientId,
+            codeVerifier,
+            codeChallenge: createHash("sha256").update(codeVerifier).digest("base64url"),
+            state: randomBytes(32).toString("base64url"),
+            redirectURI: options.extraParameters?.redirect_uri ?? redirects[this.redirectMethod],
+            toURL() {
+                const url = new URL(options.endpoint);
+                const params = {
+                    response_type: "code",
+                    client_id: request.clientId,
+                    redirect_uri: request.redirectURI,
+                    scope: options.scope,
+                    state: request.state,
+                    code_challenge: request.codeChallenge,
+                    code_challenge_method: "S256",
+                    ...options.extraParameters,
+                };
+                for (const [key, value] of Object.entries(params))
+                    url.searchParams.set(key, value);
+                return url.toString();
+            },
+        };
+        return request;
+    }
+    async authorize(options) {
+        const url = "url" in options ? options.url : options.toURL();
+        if (!["https:", "http:"].includes(new URL(url).protocol))
+            throw new TypeError("OAuth authorization URL must use HTTP or HTTPS");
+        const metadata = {
+            url,
+            providerName: this.providerName,
+            providerId: this.providerId,
+            redirectMethod: this.redirectMethod,
+        };
+        if (this.providerIcon !== undefined)
+            metadata.providerIcon = this.providerIcon;
+        if (this.description !== undefined)
+            metadata.description = this.description;
+        const result = await requestCapability("oauth.authorize", metadata);
+        if (!result ||
+            typeof result !== "object" ||
+            Array.isArray(result) ||
+            typeof result.authorizationCode !== "string")
+            throw new Error("Invalid OAuth authorization response");
+        return { authorizationCode: result.authorizationCode };
+    }
+    async setTokens(options) {
+        const values = "access_token" in options
+            ? {
+                accessToken: options.access_token,
+                refreshToken: options.refresh_token,
+                idToken: options.id_token,
+                expiresIn: options.expires_in,
+                scope: options.scope,
+            }
+            : options;
+        const tokens = { accessToken: values.accessToken };
+        for (const key of ["refreshToken", "idToken", "expiresIn", "scope"]) {
+            const value = values[key];
+            if (value !== undefined)
+                tokens[key] = Array.isArray(value) ? value.join(" ") : value;
+        }
+        await requestCapability("oauth.tokens.set", {
+            providerId: this.providerId,
+            tokens,
+            ...(this.revocationEndpoint === undefined
+                ? {}
+                : { revocationEndpoint: this.revocationEndpoint }),
+        });
+    }
+    async getTokens() {
+        const value = await requestCapability("oauth.tokens.get", { providerId: this.providerId });
+        if (value === null)
+            return undefined;
+        const tokens = value;
+        const updatedAt = new Date(tokens.updatedAt);
+        return {
+            ...tokens,
+            updatedAt,
+            isExpired: () => tokens.expiresIn !== undefined &&
+                Date.now() >= updatedAt.getTime() + tokens.expiresIn * 1000 - 10000,
+        };
+    }
+    async removeTokens() {
+        await requestCapability("oauth.tokens.remove", { providerId: this.providerId });
+    }
+}
+export const OAuth = { ...enums, clientIdMetadataDocument, PKCEClient };

package/dist/api/open.d.ts

@@ -0,0 +1,18 @@
+import type { JsonValue } from "../reconciler/index.js";
+/** `Application` from the declarations. */
+export interface Application {
+    /** The display name of the application. */
+    name: string;
+    /** The localized name of the application. */
+    localizedName?: string;
+    /** The absolute path to the application bundle. */
+    path: string;
+    /** The bundle identifier of the application. */
+    bundleId?: string;
+    /** The Windows App ID of the application. */
+    windowsAppId?: string;
+}
+/** Whether the target is a link rather than a file; a `file:` URL is a file. */
+export declare function isUrl(target: string): boolean;
+export declare function applicationParam(application: Application | string | undefined): JsonValue | undefined;
+export declare function open(target: string, application?: Application | string): Promise<void>;

package/dist/api/open.js

@@ -0,0 +1,36 @@
+import { requestCapability } from "./capability.js";
+/** Whether the target is a link rather than a file; a `file:` URL is a file. */
+export function isUrl(target) {
+    // `URL.canParse` rejects plain file paths.
+    if (!URL.canParse(target))
+        return false;
+    // A `file:` URL names a file, so granting `open.url` must not open it.
+    return new URL(target).protocol !== "file:";
+}
+// The host records the application as an identifier: a JSON-safe subset of the
+// object, so nothing unserializable can reach the wire. Shared with the
+// actions that also carry an application (`Action.Open`,
+// `Action.CreateQuicklink`).
+export function applicationParam(application) {
+    if (application === undefined)
+        return undefined;
+    if (typeof application === "string")
+        return application;
+    const param = {};
+    for (const field of ["name", "path", "bundleId", "windowsAppId"]) {
+        const value = application[field];
+        if (typeof value === "string")
+            param[field] = value;
+    }
+    return param;
+}
+export async function open(target, application) {
+    if (typeof target !== "string" || target === "")
+        throw new TypeError("open: target must be a non-empty string");
+    const url = isUrl(target);
+    const params = url ? { url: target } : { path: target };
+    const requested = applicationParam(application);
+    if (requested !== undefined)
+        params.application = requested;
+    await requestCapability(url ? "open.url" : "open.path", params);
+}

package/dist/api/preferences.d.ts

@@ -0,0 +1,43 @@
+import type { JsonValue } from "@blastlauncher/protocol";
+export type PreferenceValues = Record<string, JsonValue>;
+/** The preference kinds the manifest defines, exactly as the declarations list them. */
+export type PreferenceType = "appPicker" | "checkbox" | "dropdown" | "password" | "textfield" | "file" | "directory";
+/** `Preference`: one manifest preference item with the value this command got. */
+export interface Preference {
+    /** The name of the preference. */
+    name: string;
+    /** The type of the preference. */
+    type: PreferenceType;
+    /** Specifies if the preference is required. */
+    required: boolean;
+    /** The title of the preference. */
+    title: string;
+    /** The description of the preference. */
+    description: string;
+    /** The value of the preference. */
+    value?: unknown;
+    /** The default value when there is no `value`. */
+    default?: unknown;
+    /** A placeholder used for text fields and passwords. */
+    placeholder?: string;
+    /** A label used for checkboxes. */
+    label?: string;
+    /** The data used for dropdowns. */
+    data?: unknown[];
+}
+/** `Preferences`: the deprecated record of preference items. */
+export type Preferences = Record<string, Preference>;
+/**
+ * The deprecated `preferences` object. It is mutated in place rather than
+ * replaced so extension modules that import it keep seeing the values from
+ * `init`; each entry's `value` is the same value `getPreferenceValues()` returns.
+ */
+export declare const preferences: Preferences;
+/** Installs the preference values from `init`. */
+export declare function setPreferenceValues(next: PreferenceValues): void;
+/** The preference values for this command, as a fresh shallow copy. */
+export declare function getPreferenceValues<Values extends PreferenceValues = PreferenceValues>(): Values;
+/** Opens Raycast's preference window and selects the current extension. */
+export declare function openExtensionPreferences(): Promise<void>;
+/** Opens Raycast's preference window and selects the current command. */
+export declare function openCommandPreferences(): Promise<void>;

package/dist/api/preferences.js

@@ -0,0 +1,41 @@
+import { requestCapability } from "./capability.js";
+let preferenceValues = {};
+/**
+ * The deprecated `preferences` object. It is mutated in place rather than
+ * replaced so extension modules that import it keep seeing the values from
+ * `init`; each entry's `value` is the same value `getPreferenceValues()` returns.
+ */
+export const preferences = {};
+function installPreferences(values) {
+    for (const name of Object.keys(preferences))
+        delete preferences[name];
+    for (const [name, value] of Object.entries(values)) {
+        // `init` carries values only, so the manifest metadata the declarations
+        // require falls back to the preference's name and the text-field defaults.
+        preferences[name] = {
+            name,
+            type: "textfield",
+            required: false,
+            title: name,
+            description: "",
+            value,
+        };
+    }
+}
+/** Installs the preference values from `init`. */
+export function setPreferenceValues(next) {
+    preferenceValues = next;
+    installPreferences(next);
+}
+/** The preference values for this command, as a fresh shallow copy. */
+export function getPreferenceValues() {
+    return { ...preferenceValues };
+}
+/** Opens Raycast's preference window and selects the current extension. */
+export async function openExtensionPreferences() {
+    await requestCapability("preferences.open", { scope: "extension" });
+}
+/** Opens Raycast's preference window and selects the current command. */
+export async function openCommandPreferences() {
+    await requestCapability("preferences.open", { scope: "command" });
+}

package/dist/api/selection.d.ts

@@ -0,0 +1,10 @@
+import type { PathLike } from "node:fs";
+import type { Application } from "./open.js";
+export interface FileSystemItem {
+    path: string;
+}
+export declare function getSelectedText(): Promise<string>;
+export declare function getSelectedFinderItems(): Promise<FileSystemItem[]>;
+export declare function getFrontmostApplication(): Promise<Application>;
+export declare function showInFinder(path: PathLike): Promise<void>;
+export declare function trash(path: PathLike | PathLike[]): Promise<void>;

package/dist/api/selection.js

@@ -0,0 +1,31 @@
+import { pathParam, toApplication } from "./applications.js";
+import { requestCapability } from "./capability.js";
+export async function getSelectedText() {
+    const value = await requestCapability("selection.text", {});
+    if (typeof value !== "string")
+        throw new TypeError("getSelectedText: invalid host response");
+    if (value === "")
+        throw new Error("No text selected");
+    return value;
+}
+export async function getSelectedFinderItems() {
+    const value = await requestCapability("selection.files", {});
+    if (!Array.isArray(value))
+        throw new TypeError("getSelectedFinderItems: invalid host response");
+    return value.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item) || typeof item.path !== "string") {
+            throw new TypeError("getSelectedFinderItems: invalid FileSystemItem");
+        }
+        return { path: item.path };
+    });
+}
+export async function getFrontmostApplication() {
+    return toApplication(await requestCapability("applications.frontmost", {}), "getFrontmostApplication");
+}
+export async function showInFinder(path) {
+    await requestCapability("finder.show", { path: pathParam(path, "showInFinder") });
+}
+export async function trash(path) {
+    const paths = (Array.isArray(path) ? path : [path]).map((item) => pathParam(item, "trash"));
+    await requestCapability("trash", { paths });
+}

package/dist/api/slot.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+/**
+ * Element-valued props (`actions`, `detail`, …) cannot live inside serializable
+ * props, so the shim renders each one as a `Slot` host child named after the
+ * prop, containing the element. See "Scene conventions" in docs/architecture.md.
+ */
+export declare function slot(name: string, element: ReactNode): ReactNode;

package/dist/api/slot.js

@@ -0,0 +1,11 @@
+import { createElement } from "react";
+/**
+ * Element-valued props (`actions`, `detail`, …) cannot live inside serializable
+ * props, so the shim renders each one as a `Slot` host child named after the
+ * prop, containing the element. See "Scene conventions" in docs/architecture.md.
+ */
+export function slot(name, element) {
+    if (element === null || element === undefined || typeof element === "boolean")
+        return null;
+    return createElement("Slot", { name }, element);
+}

package/dist/api/storage.d.ts

@@ -0,0 +1,24 @@
+/** `LocalStorage.Value` (the deprecated `LocalStorageValue` alias). */
+export type LocalStorageValue = string | number | boolean;
+/** `LocalStorage.Values` (the deprecated `LocalStorageValues` alias). */
+export interface LocalStorageValues {
+    [key: string]: LocalStorageValue;
+}
+declare function getItem<T extends LocalStorageValue = LocalStorageValue>(key: string): Promise<T | undefined>;
+declare function setItem(key: string, value: LocalStorageValue): Promise<void>;
+declare function removeItem(key: string): Promise<void>;
+declare function allItems<T extends LocalStorageValues = LocalStorageValues>(): Promise<T>;
+declare function clear(): Promise<void>;
+export declare const LocalStorage: {
+    getItem: typeof getItem;
+    setItem: typeof setItem;
+    removeItem: typeof removeItem;
+    allItems: typeof allItems;
+    clear: typeof clear;
+};
+export declare const getLocalStorageItem: typeof getItem;
+export declare const setLocalStorageItem: typeof setItem;
+export declare const removeLocalStorageItem: typeof removeItem;
+export declare const allLocalStorageItems: typeof allItems;
+export declare const clearLocalStorage: typeof clear;
+export {};

package/dist/api/storage.js

@@ -0,0 +1,45 @@
+// `LocalStorage`, backed by the host's `storage.*` capabilities. Only keys and
+// values cross the process boundary; the host keys the store by the session's
+// extension, so the extension name never appears here or in params.
+import { requestCapability } from "./capability.js";
+function checkKey(key, api) {
+    if (typeof key !== "string" || key === "")
+        throw new TypeError(`${api}: key must be a non-empty string`);
+    return key;
+}
+function checkValue(value, api) {
+    if (typeof value !== "string" &&
+        !(typeof value === "number" && Number.isFinite(value)) &&
+        typeof value !== "boolean") {
+        throw new TypeError(`${api}: value must be a string, number or boolean`);
+    }
+    return value;
+}
+async function getItem(key) {
+    checkKey(key, "LocalStorage.getItem");
+    // The host answers `null` for a key it does not have.
+    const value = await requestCapability("storage.get", { key });
+    return (value ?? undefined);
+}
+async function setItem(key, value) {
+    checkKey(key, "LocalStorage.setItem");
+    checkValue(value, "LocalStorage.setItem");
+    await requestCapability("storage.set", { key, value });
+}
+async function removeItem(key) {
+    checkKey(key, "LocalStorage.removeItem");
+    await requestCapability("storage.remove", { key });
+}
+async function allItems() {
+    return (await requestCapability("storage.all", {}));
+}
+async function clear() {
+    await requestCapability("storage.clear", {});
+}
+export const LocalStorage = { getItem, setItem, removeItem, allItems, clear };
+// Deprecated top-level aliases from the declarations.
+export const getLocalStorageItem = getItem;
+export const setLocalStorageItem = setItem;
+export const removeLocalStorageItem = removeItem;
+export const allLocalStorageItems = allItems;
+export const clearLocalStorage = clear;

package/dist/api/types.d.ts

@@ -0,0 +1,46 @@
+/** `Color.Raw`: any of the literal color formats Raycast accepts. */
+export type ColorRaw = string;
+/** `Color.Dynamic`: a light/dark pair with optional contrast adjustment. */
+export type ColorDynamic = {
+    light: ColorRaw;
+    dark: ColorRaw;
+    adjustContrast?: boolean | null;
+};
+/** `Color.ColorLike`: a built-in color, a literal, or a dynamic pair. */
+export type ColorLike = string | ColorDynamic;
+/** `Image.URL` / `Image.Asset`: a remote URL or an `assets/` file name. */
+export type ImagePath = string;
+/** `Image.Source` / `Image.Fallback` for the light and dark themes. */
+export type ImageThemeSource = {
+    light: ImagePath;
+    dark: ImagePath;
+};
+/** `Image.Source`: a URL, asset, icon name, emoji, or a theme-aware pair. */
+export type ImageSource = ImagePath | ImageThemeSource;
+/** `Image.Fallback`: the source to use when `Image.source` cannot be loaded. */
+export type ImageFallback = ImagePath | ImageThemeSource;
+/** The `Image` object: a source with optional fallback, mask and tint. */
+export type ImageObject = {
+    source: ImageSource;
+    fallback?: ImageFallback | null;
+    mask?: string | null;
+    tintColor?: ColorLike | null;
+};
+/** `FileIcon`: an icon derived by the client from a file path. */
+export type FileIcon = {
+    fileIcon: string;
+};
+/** `Image.ImageLike`: a URL, asset, icon, emoji, file icon or image object. */
+export type ImageLike = ImagePath | FileIcon | ImageObject;
+/** One platform's `Keyboard.Shortcut`, widened to what reaches the scene. */
+export interface KeyShortcut {
+    modifiers: string[];
+    key: string;
+}
+/** `Keyboard.Shortcut`: one shortcut, or one per platform. */
+export type Shortcut = KeyShortcut | {
+    macOS: KeyShortcut;
+    Windows: KeyShortcut;
+    /** @deprecated Use `Windows` instead. */
+    windows?: KeyShortcut;
+};

package/dist/api/types.js

@@ -0,0 +1,5 @@
+// Types mirroring the parts of the Raycast declarations the shim implements.
+// Image-likes and color-likes keep their declared shapes, so the serialized
+// form stays the one extensions authored; shortcut shapes are widened to what
+// reaches the scene as JSON.
+export {};

package/dist/api/unsupported.d.ts

@@ -0,0 +1,18 @@
+export declare class UnsupportedApiError extends Error {
+    readonly code = "UNSUPPORTED_API";
+    readonly path: string;
+    constructor(path: string);
+}
+/** Present on stubs only: the unsupported path. Lets the serializer reject stub values. */
+export declare const UNSUPPORTED_PATH: unique symbol;
+export declare function unsupportedPath(value: unknown): string | undefined;
+export type ApiStub = {
+    (...args: unknown[]): never;
+    new (...args: unknown[]): ApiStub;
+    [key: string]: ApiStub;
+};
+/** Preserve real implementations, while lazily supplying missing namespace members.
+ * Probe properties used by React and Promise resolution must retain normal semantics.
+ */
+export declare function withUnsupported<T>(path: string, implemented?: T): T & Record<string, ApiStub>;
+export declare function createApi<T extends object>(implemented: T): <K extends string>(path: K) => K extends keyof T ? T[K] & Record<string, ApiStub> : ApiStub;