@raycast/api 1.27.1 → 1.29.1

package/types/api/ui/feedback/hud.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A HUD will automatically hide the main window and show a compact message at the bottom of the screen.
+ *
+ * @param title - The title that will be displayed in the HUD.
+ * @returns A Promise that resolves when the HUD is shown.
+ *
+ * @example
+ * ```typescript
+ * import { showHUD } from "@raycast/api";
+ *
+ * export default async () => {
+ *   await showHUD("Hey there 👋");
+ * };
+ * ```
+ */
+export declare function showHUD(title: string): Promise<void>;

package/types/api/ui/feedback/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./alert";
+export { showToast, Toast } from "./toast";
+export * from "./hud";

package/types/api/ui/feedback/toast.d.ts

@@ -0,0 +1,174 @@
+import { Keyboard } from "../../app";
+/**
+ * Creates and shows a Toast with the given {@link Toast.Options}.
+ *
+ * @param options - The options to customize the Toast.
+ * @returns A Promise that resolves with the shown Toast. The Toast can be used to change or hide it.
+ *
+ * @example
+ * ```typescript
+ * import { showToast, Toast } from "@raycast/api";
+ *
+ * export default async () => {
+ *   const success = false;
+ *
+ *   if (success) {
+ *     await showToast({ title: "Dinner is ready", message: "Pizza margherita" });
+ *   } else {
+ *     await showToast({ style: Toast.Style.Failure, title: "Dinner isn't ready", message: "Pizza dropped on the floor" });
+ *   }
+ * };
+ * ```
+ *
+ * When showing an animated Toast, you can later on update it:
+ * @example
+ * ```typescript
+ * import { showToast, Toast } from "@raycast/api";
+ * import { setTimeout } from "timers/promises";
+ *
+ * export default async () => {
+ *   const toast = await showToast({ style: Toast.Style.Animated, title: "Uploading image" });
+ *
+ *   try {
+ *    // upload the image
+ *    await setTimeout(1000);
+ *
+ *    toast.style = Toast.Style.Success;
+ *    toast.title = "Uploaded image";
+ *  } catch (err) {
+ *    toast.style = Toast.Style.Failure;
+ *    toast.title = "Failed to upload image";
+ *    toast.message = err.message;
+ *  }
+ * };
+ * ```
+ */
+export declare function showToast(options: Toast.Options): Promise<Toast>;
+export declare function showToast(style: Toast.Style, title: string, message?: string): Promise<Toast>;
+/**
+ * A Toast with a certain style, title, and message.
+ *
+ * @example
+ * ```typescript
+ * import { showToast, Toast } from "@raycast/api";
+ * import { setTimeout } from "timers/promises";
+ *
+ * export default async () => {
+ *   const toast = await showToast({ style: Toast.Style.Animated, title: "Uploading image" });
+ *
+ *   await setTimeout(1000);
+ *
+ *   toast.style = Toast.Style.Success;
+ *   toast.title = "Uploaded image";
+ * };
+ * ```
+ */
+export declare class Toast {
+    private options;
+    private id;
+    private callbacks;
+    /**
+     * Deprecated - Use `showToast` instead
+     */
+    constructor(props: Toast.Options);
+    get style(): Toast.Style;
+    set style(style: Toast.Style);
+    get title(): string;
+    set title(title: string);
+    get message(): string | undefined;
+    set message(message: string | undefined);
+    get primaryAction(): Toast.ActionOptions | undefined;
+    set primaryAction(action: Toast.ActionOptions | undefined);
+    get secondaryAction(): Toast.ActionOptions | undefined;
+    set secondaryAction(action: Toast.ActionOptions | undefined);
+    /**
+     * Shows the Toast.
+     *
+     * @returns A Promise that resolves when the toast is shown.
+     */
+    show(): Promise<void>;
+    /**
+     * Hides the Toast.
+     *
+     * @returns A Promise that resolves when toast is hidden.
+     */
+    hide(): Promise<void>;
+    private update;
+}
+export declare namespace Toast {
+    /**
+     * The options to create a {@link Toast}.
+     *
+     * @example
+     * ```typescript
+     * import { showToast, Toast } from "@raycast/api";
+     *
+     * export default async () => {
+     *   const options: Toast.Options = {
+     *     style: Toast.Style.Success,
+     *     title: "Finished cooking",
+     *     message: "Delicious pasta for lunch",
+     *     primaryAction: {
+     *       title: 'Do something',
+     *       onAction: () => {
+     *         console.log("The toast action has been triggered")
+     *       }
+     *     }
+     *   };
+     *   await showToast(options);
+     * };
+     * ```
+     */
+    interface Options {
+        /**
+         * The title of a Toast. Displayed on the top.
+         */
+        title: string;
+        /**
+         * An additional message for the Toast. Useful to show more information, e.g. an identifier of a newly created asset.
+         */
+        message?: string;
+        /**
+         * The style of a Toast.
+         */
+        style?: Style;
+        /**
+         * The primary Action the user can take when hovering on the Toast.
+         */
+        primaryAction?: ActionOptions;
+        /**
+         * The secondary Action the user can take when hovering on the Toast.
+         */
+        secondaryAction?: ActionOptions;
+    }
+    /**
+     * The options to create a {@link Toast} Action.
+     */
+    interface ActionOptions {
+        /**
+         * The title of the action.
+         */
+        title: string;
+        /**
+         * The keyboard shortcut for the action.
+         */
+        shortcut?: Keyboard.Shortcut;
+        /**
+         * A callback called when the action is triggered.
+         */
+        onAction: (toast: Toast) => void;
+    }
+    /**
+     * Defines the visual style of the Toast.
+     *
+     * @remarks
+     * Use {@link Toast.Style.Success} for confirmations and {@link Toast.Style.Failure} for displaying errors.
+     * Use {@link Toast.Style.Animated} when your Toast should be shown until a process is completed.
+     * You can hide it later by using {@link Toast.hide} or update the properties of an existing Toast.
+     */
+    enum Style {
+        Success = "SUCCESS",
+        Failure = "FAILURE",
+        Animated = "ANIMATED"
+    }
+}

package/types/api/ui/icon.d.ts

@@ -0,0 +1,88 @@
+/**
+ * List of built-in icons that can be used for actions or list items.
+ *
+ * @example
+ * ```typescript
+ * import { Icon, List } from "@raycast/api";
+ *
+ * export default function Command() {
+ *   return (
+ *     <List>
+ *       <List.Item title="Icon" icon={Icon.Circle} />
+ *     </List>
+ *   );
+ * };
+ * ```
+ */
+export declare enum Icon {
+    ArrowClockwise = "arrow-clockwise-16",
+    ArrowRight = "arrow-right-16",
+    Binoculars = "binoculars-16",
+    Bubble = "bubble-left-16",
+    Calendar = "calendar-16",
+    Checkmark = "checkmark-circle-16",
+    ChevronDown = "chevron-down-16",
+    ChevronUp = "chevron-up-16",
+    Circle = "circle-16",
+    Clipboard = "doc-on-clipboard-16",
+    Clock = "clock-16",
+    Desktop = "desktopcomputer-16",
+    Document = "doc-16",
+    Dot = "dot-16",
+    Download = "square-and-arrow-down-16",
+    Envelope = "envelope-16",
+    ExclamationMark = "exclamation-mark-triangle-16",
+    Eye = "eye-16",
+    EyeSlash = "eye-slash-16",
+    Finder = "finder-16",
+    Gear = "gearshape-16",
+    Globe = "globe-16",
+    Hammer = "hammer-16",
+    LevelMeter = "level-meter-16",
+    Link = "link-16",
+    List = "main-list-view-16",
+    MagnifyingGlass = "magnifyingglass-16",
+    MemoryChip = "memorychip-16",
+    Message = "message-16",
+    Pencil = "pencil-16",
+    Person = "person-crop-circle-16",
+    Phone = "phone-16",
+    Pin = "pin-16",
+    Plus = "plus-16",
+    Sidebar = "sidebar-right-16",
+    SpeakerArrowDown = "speaker-arrow-down-16",
+    SpeakerArrowUp = "speaker-arrow-up-16",
+    SpeakerSlash = "speaker-slash-16",
+    Star = "star-16",
+    Text = "text-alignleft-16",
+    TextDocument = "doc-plaintext-16",
+    QuestionMark = "questionmark-circle-16",
+    Terminal = "terminal-16",
+    Trash = "trash-16",
+    Upload = "square-and-arrow-up-16",
+    Video = "video-16",
+    Window = "macwindow-16",
+    XmarkCircle = "xmark-circle-16"
+}
+/**
+ * An icon as it's used in the Finder.
+ *
+ * @example
+ * ```typescript
+ * import { List } from "@raycast/api";
+ *
+ * export default function Command() {
+ *   return (
+ *     <List>
+ *       <List.Item title="File icon" icon={{ fileIcon: __filename }} />
+ *     </List>
+ *   );
+ * };
+ * ```
+ */
+export interface FileIcon {
+    /**
+     * The path to a file or folder to get its icon from.
+     */
+    fileIcon: string;
+}

package/types/api/ui/image.d.ts

@@ -0,0 +1,162 @@
+import { Color } from "./color";
+import { FileIcon, Icon } from "./icon";
+/**
+ * Display different types of images, including network images or bundled assets.
+ *
+ * @example
+ * ```typescript
+ * // Built-in icon
+ * const icon = Icon.Eye
+ *
+ * // Built-in icon with tint color
+ * const tintedIcon = { source: Icon.Bubble, tintColor: Color.Red }
+ *
+ * // Bundled asset with circular mask
+ * const avatar = { source: "avatar.png", mask: Image.Mask.Circle }
+ *
+ * // Theme-aware icon
+ * const icon = { source: { light: "icon-light.png", dark: "icon-dark.png" }}
+ * ```
+ *
+ * @remark
+ * Apply image transforms to the source, such as a `mask` or a `tintColor`.
+ */
+export interface Image {
+    /**
+     * The {@link Image.Source} of the image.
+     */
+    source: Image.Source;
+    /**
+     * {@link Image.Fallback} image, in case `source` can't be loaded.
+     */
+    fallback?: Image.Fallback;
+    /**
+     * A {@link Image.Mask} to apply to the image.
+     */
+    mask?: Image.Mask;
+    /**
+     * A {@link Color.ColorLike} to tint all the non-transparent pixels of the image.
+     */
+    tintColor?: Color.ColorLike;
+}
+export declare namespace Image {
+    /**
+     * Image is a string representing a URL.
+     */
+    type URL = string;
+    /**
+     * Image is a string denoting an asset from the `assets/` folder.
+     */
+    type Asset = string;
+    /**
+     * Union type for the supported image types.
+     *
+     * @example
+     * ```typescript
+     * import { Icon, Image, List } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <List>
+     *       <List.Item title="String" icon="https://raycast.com/uploads/avatar.png" />
+     *       <List.Item title="Icon" icon={Icon.Circle} />
+     *       <List.Item title="FileIcon" icon={{ fileIcon: __filename }} />
+     *       <List.Item title="Image" icon={{ source: "https://raycast.com/uploads/avatar.png", mask: Image.Mask.Circle }} />
+     *     </List>
+     *   );
+     * };
+     * ```
+     */
+    type ImageLike = URL | Asset | Icon | FileIcon | Image;
+    /**
+     * The source of an {@link Image}. Can be either a remote URL, a local file resource, a built-in {@link Icon} or
+     * a single emoji.
+     *
+     * @remarks
+     * For consistency, it's best to use the built-in {@link Icon} in lists, the Action Panel, and other places. If a
+     * specific icon isn't built-in, you can reference custom ones from the `assets` folder of the extension by file name,
+     * e.g. `my-icon.png`. Alternatively, you can reference an absolute HTTPS URL that points to an image or use an emoji.
+     * You can also specify different remote or local assets for light and dark theme.
+     *
+     * @example
+     * ```typescript
+     * import { Icon, List } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <List>
+     *       <List.Item title="String" icon={{ source: "https://raycast.com/uploads/avatar.png" }} />
+     *       <List.Item title="Icon" icon={{ source: Icon.Circle }} />
+     *       <List.Item
+     *         title="Theme"
+     *         icon={{
+     *           source: { light: "https://raycast.com/uploads/avatar.png", dark: "https://raycast.com/uploads/avatar.png" },
+     *         }}
+     *       />
+     *     </List>
+     *   );
+     * };
+     * ```
+     */
+    type Source = URL | Asset | Icon | {
+        light: URL | Asset;
+        dark: URL | Asset;
+    };
+    /**
+     * Fallback {@link Image} source. Can be a local file resource, a built-in {@link Icon}, a single emoji, or a theme-aware asset.
+     * Any specified `mask` or `tintColor` will also apply to the fallback image.
+     *
+     * @example
+     * ```typescript
+     * import { Icon, List } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <List>
+     *       <List.Item title="String" icon={{ source: "https://raycast.com/uploads/avatar.png", fallback: Icon.Circle }} />
+     *       <List.Item title="Icon" icon={{ source: Icon.Circle }} />
+     *       <List.Item
+     *         title="Theme"
+     *         icon={{
+     *           source: { light: "https://raycast.com/uploads/avatar.png", dark: "https://raycast.com/uploads/avatar.png" },
+     *         }}
+     *       />
+     *     </List>
+     *   );
+     * };
+     * ```
+     */
+    type Fallback = Asset | Icon | {
+        light: Asset;
+        dark: Asset;
+    };
+    /**
+     * Available masks that can be used to change the shape of an image.
+     *
+     * @remarks
+     * Can be handy to shape avatars or other items in a list.
+     *
+     * @example
+     * ```typescript
+     * import { Image, List } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <List>
+     *       <List.Item title="Icon" icon={{ source: "https://raycast.com/uploads/avatar.png", mask: Image.Mask.Circle }} />
+     *     </List>
+     *   );
+     * };
+     * ```
+     */
+    enum Mask {
+        /**
+         * Masks an image with a circle. Good to use for avatars.
+         */
+        Circle = "circle",
+        /**
+         * Masks an image with a rounded rectangle.
+         */
+        RoundedRectangle = "roundedRectangle"
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from "./color";
+export * from "./errors";
+export * from "./icon";
+export * from "./image";
+export * from "./feedback";

package/types/core/message-types.d.ts

@@ -0,0 +1,17 @@
+export declare type WorkerMessage = RequestMessage | NotifyMessage | ResultMessage;
+export declare type RequestMessage = {
+    kind: "request";
+    id: string;
+    method: string;
+    params: MessageParams;
+};
+export declare type NotifyMessage = {
+    kind: "notify";
+    method: string;
+    params: MessageParams;
+};
+export declare type ResultMessage = {
+    kind: "result";
+    id: string;
+    result: MessageResult;
+};

package/types/core/preferences.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A record type holding the preferences (entered in Raycast Preferences) that have been passed to the command.
+ */
+export declare type Preferences = Record<string, Preference>;
+/**
+ * Holds data about a single preference item (entered in Raycast Preferences).
+ *
+ * @remarks
+ * The object maps to a defined preference in the `package.json` manifest file.
+ */
+export interface Preference {
+    /**
+     * The name of the preference.
+     */
+    name: string;
+    /**
+     * The type of the preference.
+     */
+    type: "appPicker" | "checkbox" | "dropdown" | "password" | "textfield";
+    /**
+     * Specifies if the preference is required.
+     *
+     * @remarks
+     * If the preference is required, an onboarding view is shown when the
+     * extension is opened for the first time.
+     *
+     * @defaultValue false
+     */
+    required: boolean;
+    /**
+     * The title of the preference.
+     *
+     * @remarks
+     * The title is also shown in the Raycast preferences.
+     */
+    title: string;
+    /**
+     * The description of the preference.
+     *
+     * @remarks
+     * The description is shown in the Raycast preferences as well as in the
+     * onboarding view for required preferences.
+     */
+    description: string;
+    /**
+     * The value of the preference.
+     */
+    value?: unknown;
+    /**
+     * The default value of the preference if there is no `value` specified.
+     * For dropdowns, this references the `value` property of an object in the data array.
+     * For app pickers, this references an application name, bundleId or path."
+     */
+    default?: unknown;
+    /**
+     * A placeholder that is used for text fields and passwords.
+     */
+    placeholder?: string;
+    /**
+     * A label that is used for checkboxes.
+     * You can create checkbox groups by setting this property and leaving the title property empty for all checkboxes except the first.
+     */
+    label?: string;
+    /**
+     * The data that is used for dropdowns.
+     * For the dropdown items, add an array of objects with `title` and `value` properties, such as: `{"title": "Foo", "value": "bar"}`
+     */
+    data?: unknown[];
+}