@raycast/api 1.27.1 → 1.29.1

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@raycast/api",
-  "version": "1.27.1",
+  "version": "1.29.1",
   "description": "Build extensions for Raycast with React and Node.js.",
   "author": "Raycast Technologies Ltd.",
   "homepage": "https://developers.raycast.com",
   "license": "MIT",
-  "types": "types/index.d.ts",
+  "types": "types/api/index.d.ts",
   "peerDependencies": {
     "react": "17.0.2",
     "react-reconciler": "0.26.2"

package/types/api/app/app.d.ts

@@ -0,0 +1,171 @@
+/// <reference types="node" />
+import { PathLike } from "fs";
+/**
+ * Closes the main Raycast window.
+ *
+ * @param options - Can be used to clear the root search. Defaults to not clearing the root search after
+ * the window was closed.
+ * @returns A Promise that resolves when the main window is closed.
+ *
+ * @example
+ * ```typescript
+ * import { closeMainWindow } from "@raycast/api";
+ * import { setTimeout } from "timers/promises";
+ *
+ * export default async () => {
+ *   await setTimeout(1000);
+ *   await closeMainWindow({ clearRootSearch: true });
+ * };
+ * ```
+ */
+export declare function closeMainWindow(options?: {
+    clearRootSearch?: boolean;
+}): Promise<void>;
+/**
+ * Pops the navigation stack back to root search.
+ *
+ * @param options - Can be used to clear the search bar. Defaults to clearing the search bar after popped to root.
+ * @returns A Promise that resolves when Raycast popped to root.
+ *
+ * @example
+ * ```typescript
+ * import { Detail, popToRoot } from "@raycast/api";
+ * import { useEffect } from "react";
+ * import { setTimeout } from "timers";
+ *
+ * export default function Command() {
+ *   useEffect(() => {
+ *     setTimeout(() => {
+ *       popToRoot({ clearSearchBar: true });
+ *     }, 3000);
+ *   }, []);
+ *
+ *   return <Detail markdown="See you soon 👋" />;
+ * }
+ * ```
+ */
+export declare function popToRoot(options?: {
+    clearSearchBar?: boolean;
+}): Promise<void>;
+/**
+ * Clear the text in the search bar.
+ *
+ * @param options - Can be used to force scrolling to the top. Defaults to scrolling to the top after the
+ * the search bar was cleared.
+ * @returns A Promise that resolves when the search bar is cleared.
+ */
+export declare function clearSearchBar(options?: {
+    forceScrollToTop?: boolean;
+}): Promise<void>;
+/**
+ * Utils
+ */
+/**
+ * Shows a file or directory in the Finder.
+ *
+ * @param path - The path to show in the Finder.
+ * @returns A Promise that resolves when the item is revealed in the Finder.
+ *
+ * @example
+ * ```typescript
+ * import { showInFinder } from "@raycast/api"
+ * import { homedir } from "os"
+ * import { join } from "path"
+ * showInFinder(join(homedir(), "Downloads"))
+ * ```
+ */
+export declare function showInFinder(path: PathLike): Promise<void>;
+/**
+ * Moves a file or directory to the Trash.
+ *
+ * @param paths - The item or items to move to the trash.
+ * @returns A Promise that resolves when all files are moved to the trash.
+ *
+ * @example
+ * ```typescript
+ * import { trash } from "@raycast/api";
+ * import { writeFile } from "fs/promises";
+ * import { homedir } from "os";
+ *
+ * export default async () => {
+ *   const file = `${homedir()}/Desktop/yolo.txt`;
+ *   await writeFile(file, "I will be deleted soon!");
+ *   await trash(file);
+ * };
+ * ```
+ */
+export declare function trash(path: PathLike | PathLike[]): Promise<void>;
+/**
+ * An object that represents a locally installed application on the system.
+ *
+ * @remarks
+ * It can be used to open files or folders in a specific application. Use {@link getApplications} or
+ * {@link getDefaultApplication} to get applications that can open a specific file or folder.
+ */
+export interface Application {
+    /**
+     * The display name of the application.
+     */
+    name: string;
+    /**
+     * The absolute path to the application bundle, e.g. `/Applications/Raycast.app`,
+     */
+    path: string;
+    /**
+     * The bundle identifier of the application, e.g. `com.raycast.macos`.
+     */
+    bundleId?: string;
+}
+/**
+ * Returns all applications that can open the file.
+ *
+ * @param path The path of the file or folder to get the applications for. If no path is specified, all installed applications are returned.
+ * @returns An array of {@link Application}.
+ *
+ * @example
+ * ```typescript
+ * import { getApplications } from "@raycast/api";
+ *
+ * export default async () => {
+ *   const installedApplications = await getApplications();
+ *   console.log("The following applications are installed on your Mac:");
+ *   console.log(installedApplications.map((a) => a.name).join(", "));
+ * };
+ * ```
+ */
+export declare function getApplications(path?: PathLike): Promise<Application[]>;
+/**
+ * Returns the default application that the file would be opened with.
+ *
+ * @param path The path of the file or folder to get the default application for.
+ * @returns The default {@link Application} that would open the file. Throws an error if no application was found.
+ *
+ * @example
+ * ```typescript
+ * import { getDefaultApplication } from "@raycast/api";
+ *
+ * export default async () => {
+ *   const defaultApplication = await getDefaultApplication(__filename);
+ *   console.log(`Default application for JavaScript is: ${defaultApplication.name}`);
+ * };
+ * ```
+ */
+export declare function getDefaultApplication(path: PathLike): Promise<Application>;
+/**
+ * Opens a target with the default application or specified application.
+ *
+ * @param target The file, folder or URL to open.
+ * @param application The application name to use for opening the file. If no application is specified, the default application as determined by the system
+ * is used to open the specified file. Note that you can use the application name, app identifier, or absolute path to the app.
+ * @returns A Promise that resolves when the target has been opened.
+ *
+ * @example
+ * ```typescript
+ * import { open } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await open("https://www.raycast.com", "com.google.Chrome");
+ * };
+ * ```
+ */
+export declare function open(target: string, application?: Application | string): Promise<void>;

package/types/api/app/clipboard.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copies text to the clipboard.
+ *
+ * @param text - The text to copy to the clipboard.
+ * @returns A Promise that resolves when the text is copied to the clipboard.
+ *
+ * @example
+ * ```typescript
+ * import { Clipboard } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await Clipboard.copy("https://raycast.com");
+ * };
+ * ```
+ */
+export declare function copy(text: string): Promise<void>;
+/**
+ * Clears the current clipboard contents.
+ *
+ * @returns A Promise that resolves when the clipboard is cleared.
+ *
+ * @example
+ * ```typescript
+ * import { Clipboard } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await Clipboard.clear();
+ * };
+ * ```
+ */
+export declare function clear(): Promise<void>;
+/**
+ * Pastes text to the current selection of the frontmost application.
+ *
+ * @param text - The text to insert at the cursor.
+ * @returns A Promise that resolves when the text is pasted.
+ *
+ * @example
+ * ```typescript
+ * import { Clipboard } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await Clipboard.paste("I really like Raycast's API");
+ * };
+ * ```
+ */
+export declare function paste(text: string): Promise<void>;

package/types/api/app/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./app";
+export * as Clipboard from "./clipboard";
+export * as Keyboard from "./keyboard";
+export * as LocalStorage from "./localStorage";

package/types/api/app/keyboard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A keyboard shortcut is defined by one or more modifier keys (command, control, etc.) and a single key equivalent (a character or special key).
+ * See {@link KeyModifier} and {@link KeyEquivalent} for supported values.
+ *
+ * @example
+ * ```typescript
+ * import { ActionPanel, Detail, Action } from "@raycast/api";
+ *
+ * export default function Command() {
+ *   return (
+ *     <Detail markdown="Let's play some games 👾" actions={
+ *       <ActionPanel title="Game controls">
+ *         <Action
+ *           title="Up"
+ *           shortcut={{ modifiers: ["opt"], key: "arrowUp" }}
+ *           onAction={() => console.log("Go up")}
+ *         />
+ *         <Action
+ *           title="Down"
+ *           shortcut={{ modifiers: ["opt"], key: "arrowDown" }}
+ *           onAction={() => console.log("Go down")}
+ *         />
+ *         <Action
+ *           title="Left"
+ *           shortcut={{ modifiers: ["opt"], key: "arrowLeft" }}
+ *           onAction={() => console.log("Go left")}
+ *         />
+ *         <Action
+ *           title="Right"
+ *           shortcut={{ modifiers: ["opt"], key: "arrowRight" }}
+ *           onAction={() => console.log("Go right")}
+ *         />
+ *       </ActionPanel>}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export interface Shortcut {
+    /**
+     * The modifier keys of the keyboard shortcut.
+     */
+    modifiers: KeyModifier[];
+    /**
+     * The key of the keyboard shortcut.
+     */
+    key: KeyEquivalent;
+}
+/**
+ * Modifier of a {@link Shortcut}
+ */
+export declare type KeyModifier = "cmd" | "ctrl" | "opt" | "shift";
+/**
+ * KeyEquivalent of a {@link Shortcut}
+ */
+export declare type KeyEquivalent = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "." | "," | ";" | "=" | "+" | "-" | "[" | "]" | "{" | "}" | "«" | "»" | "(" | ")" | "/" | "\\" | "'" | "`" | "§" | "^" | "@" | "$" | "return" | "delete" | "deleteForward" | "tab" | "arrowUp" | "arrowDown" | "arrowLeft" | "arrowRight" | "pageUp" | "pageDown" | "home" | "end" | "space" | "escape" | "enter" | "backspace";

package/types/api/app/localStorage.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Retrieve all stored values in the local storage of an extension.
+ *
+ * @returns A Promise that resolves with an object containing all {@link Values}.
+ *
+ * @example
+ * ```typescript
+ * import { LocalStorage } from "@raycast/api";
+ *
+ * interface Values {
+ *   todo: string;
+ *   priority: number;
+ * }
+ *
+ * export default async () => {
+ *   const items = await LocalStorage.allItems<Values>();
+ *   console.log(`Local storage item count: ${Object.entries(items).length}`);
+ * };
+ * ```
+ */
+export declare function allItems<T extends Values = Values>(): Promise<T>;
+/**
+ * Retrieve the stored value for the given key.
+ *
+ * @param key - The key you want to retrieve the value of.
+ * @returns A Promise that resolves with the stored value for the given key. If the key does not exist, `undefined` is returned.
+ *
+ * @example
+ * ```typescript
+ * import { LocalStorage } from "@raycast/api";
+ *
+ * export default async () => {
+ *   const item = await LocalStorage.getItem<string>("favorite-fruit");
+ *   console.log(item);
+ * };
+ * ```
+ */
+export declare function getItem<T extends Value = Value>(key: string): Promise<T | undefined>;
+/**
+ * Stores a value for the given key.
+ *
+ * @param key - The key you want to create or update the value of.
+ * @param value - The value you want to create or update for the given key.
+ * @returns A Promise that resolves when the value is stored.
+ *
+ * @example
+ * ```typescript
+ * import { LocalStorage } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await LocalStorage.setItem("favorite-fruit", "cherry");
+ * };
+ * ```
+ */
+export declare function setItem(key: string, value: Value): Promise<void>;
+/**
+ * Removes the stored value for the given key.
+ *
+ * @param key - The key you want to remove the value of.
+ * @returns A Promise that resolves when the value is removed.
+ *
+ * @example
+ * ```typescript
+ * import { LocalStorage } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await LocalStorage.removeItem("favorite-fruit");
+ * };
+ * ```
+ */
+export declare function removeItem(key: string): Promise<void>;
+/**
+ * Removes all stored values of an extension.
+ *
+ * @returns A Promise that resolves when all values are removed.
+ *
+ * @example
+ * ```typescript
+ * import { LocalStorage } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await LocalStorage.clear();
+ * };
+ * ```
+ */
+export declare function clear(): Promise<void>;
+/**
+ * Supported storage value types.
+ *
+ * @example
+ * ```typescript
+ * import { LocalStorage } from "@raycast/api";
+ *
+ * export default async () => {
+ *   // string
+ *   await LocalStorage.setItem("favorite-fruit", "cherry");
+ *
+ *   // number
+ *   await LocalStorage.setItem("fruit-basket-count", 3);
+ *
+ *   // boolean
+ *   await LocalStorage.setItem("fruit-eaten-today", true);
+ * };
+ * ```
+ */
+export declare type Value = string | number | boolean;
+/**
+ * Values of local storage items.
+ *
+ * > For type-safe values, you can define your own interface. Use the keys of the local storage items as the property names.
+ */
+export interface Values {
+    /**
+     * The local storage value of a given key.
+     */
+    [key: string]: any;
+}