@raycast/api 1.38.1 → 1.39.0

package/api.d.ts

@@ -2109,6 +2109,10 @@ export declare interface Environment {
      * The name of the launched command, as specified in package.json
      */
     commandName: string;
+    /**
+     * The mode of the launched command, as specified in package.json
+     */
+    commandMode: "no-view" | "view" | "menu-bar";
     /**
      * The absolute path to the assets directory of the extension.
      *
@@ -2144,6 +2148,7 @@ export declare interface Environment {
  * console.log(`Raycast version: ${environment.raycastVersion}`);
  * console.log(`Extension name: ${environment.extensionName}`);
  * console.log(`Command name: ${environment.commandName}`);
+ * console.log(`Command mode: ${environment.commandMode}`);
  * console.log(`Assets path: ${environment.assetsPath}`);
  * console.log(`Support path: ${environment.supportPath}`);
  * console.log(`Is development mode: ${environment.isDevelopment}`);
@@ -2196,6 +2201,7 @@ export declare namespace Form {
     export type Value = FormValue_2;
     export type Values = FormValues_2;
     export type Props = FormProps_2;
+    export type ItemReference = FormItemRef;
     /**
      * An interface describing event in callbacks {@link Form.Item.Props.onFocus} and {@link Form.Item.Props.onBlur}
      */
@@ -3912,7 +3918,7 @@ declare interface GridMembers {
      * export default function Command() {
      *   return (
      *     <Grid>
-     *       <Grid.Item icon={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" />
+     *       <Grid.Item content={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" />
      *     </Grid>
      *   );
      * }
@@ -4121,6 +4127,7 @@ export declare enum Icon {
     BellDisabled = "bell-disabled-16",
     Bike = "bike-16",
     Binoculars = "binoculars-16",
+    Bird = "bird-16",
     BlankDocument = "blank-document-16",
     Bluetooth = "bluetooth-16",
     Boat = "boat-16",
@@ -4494,7 +4501,9 @@ export declare enum Icon {
     /** @deprecated Use {@link Icon.SpeakerOff} instead. */
     SpeakerSlash = "speaker-off-16",
     /** @deprecated Use {@link Icon.BlankDocument} instead. */
-    TextDocument = "blank-document-16"
+    TextDocument = "blank-document-16",
+    /** @deprecated Use {@link Icon.XMarkCircle} instead. */
+    XmarkCircle = "x-mark-circle-16"
 }
 
 /**
@@ -4851,10 +4860,25 @@ declare interface ItemProps_2 extends ActionsInterface {
 }
 
 declare interface ItemProps_3 {
+    /**
+     * The main title displayed for this item.
+     */
     title: string;
+    /**
+     * An optional icon for this item.
+     */
     icon?: Image.ImageLike;
+    /**
+     * A tooltip to display when the cursor hovers the item.
+     */
     tooltip?: string;
+    /**
+     * An action handler called when the user clicks the item.
+     */
     onAction?: () => void;
+    /**
+     * A shortcut used to invoke this item when its parent menu is open.
+     */
     shortcut?: Keyboard.Shortcut;
 }
 
@@ -4994,6 +5018,11 @@ export declare enum LaunchType {
  */
 declare const Link: FunctionComponent<LinkProps>;
 
+/**
+ * See {@link List.Item.Detail.Metadata.Link}
+ */
+declare const Link_2: FunctionComponent<LinkProps_2>;
+
 declare interface LinkProps {
     /**
      * The title shown above the item.
@@ -5009,6 +5038,21 @@ declare interface LinkProps {
     text: string;
 }
 
+declare interface LinkProps_2 {
+    /**
+     * The title shown above the item.
+     */
+    title: string;
+    /**
+     * The target of the link.
+     */
+    target: string;
+    /**
+     * The text value of the item.
+     */
+    text: string;
+}
+
 /**
  * Displays {@link List.Section} or {@link List.Item}, optionally {@link List.Dropdown}.
  *
@@ -5495,12 +5539,25 @@ declare interface MenuBarExtraMembers {
 
 declare interface MenuBarExtraProps {
     /**
+     * Indicates to Raycast that it should not unload the command, as it is still executing. If you set make use of `isLoading`, you need to make sure you set it to `false` at the end of the task you are executing (such as an API call), so Raycast can then unload the command.
      * @defaultValue `false`
      */
     isLoading?: boolean;
+    /**
+     * The string that is displayed in the menu bar.
+     */
     title?: string;
+    /**
+     * A tooltip to display when the cursor hovers the item in the menu bar.
+     */
     tooltip?: string;
+    /**
+     * The icon that is displayed in the menu bar.
+     */
     icon?: Image.ImageLike;
+    /**
+     * `MenuBarExtra.Item`s, `MenuBarExtra.Submenu`s, `MenuBarExtra.Separator` or a mix of either.
+     */
     children?: ReactNode;
 }
 
@@ -5562,6 +5619,10 @@ declare interface MetadataMembers_2 {
      * ```
      */
     Label: typeof Label_2;
+    /**
+     * An item to display a link.
+     */
+    Link: typeof Link_2;
     /**
      * A metadata item that shows a separator line. Use it for grouping and visually separating metadata items.
      *
@@ -5592,6 +5653,10 @@ declare interface MetadataMembers_2 {
      * ```
      */
     Separator: typeof Separator_3;
+    /**
+     * A list of {@link List.Item.Detail.Metadata.TagList.Item} displayed in a row.
+     */
+    TagList: typeof TagList_2;
 }
 
 declare interface MetadataProps {
@@ -6710,11 +6775,17 @@ declare interface SubmenuProps {
 }
 
 declare interface SubmenuProps_2 {
-    title: string | {
-        value: string;
-        tooltip: string;
-    };
+    /**
+     * The main title displayed for this submenu.
+     */
+    title: string;
+    /**
+     * An optional icon for this submenu.
+     */
     icon?: Image.ImageLike;
+    /**
+     * `MenuBarExtra.Item`s, `MenuBarExtra.Submenu`s, `MenuBarExtra.Separator` or a mix of either.
+     */
     children?: ReactNode;
 }
 
@@ -6761,8 +6832,12 @@ declare interface SubmitFormProps<T extends Form.Values> {
      * Callback that is triggered when the submit was submitted.
      * Use the handler to perform custom validation logic and call other Raycast API methods.
      * The handler receives a the values object containing the user input.
+     *
+     * @returns You can optionally return `false` to indicate that the submit action failed. Raycast will show some subtle feedback to the user that something went wrong. Pair it with the Form inputs' `validation` for a top-notch user experience.
+     *
+     * _If a user has the Accessibility setting 'Reduce Motion' enabled, Raycast won't show the feedback._
      */
-    onSubmit?: (input: T) => void;
+    onSubmit?: (input: T) => void | boolean | Promise<void | boolean>;
 }
 
 /**
@@ -6770,11 +6845,21 @@ declare interface SubmitFormProps<T extends Form.Values> {
  */
 declare const TagList: FunctionComponent<TagListProps> & TagListMembers;
 
+/**
+ * See {@link List.Item.Detail.Metadata.TagList}
+ */
+declare const TagList_2: FunctionComponent<TagListProps_2> & TagListMembers_2;
+
 /**
  * See {@link Detail.Metadata.TagList.Item}
  */
 declare const TagListItem: FunctionComponent<TagListItemProps>;
 
+/**
+ * See {@link Detail.Metadata.TagList.Item}
+ */
+declare const TagListItem_2: FunctionComponent<TagListItemProps_2>;
+
 declare interface TagListItemProps {
     /**
      * An optional icon in front of the text of the tag.
@@ -6790,6 +6875,21 @@ declare interface TagListItemProps {
     color?: Color.ColorLike | undefined | null;
 }
 
+declare interface TagListItemProps_2 {
+    /**
+     * An optional icon in front of the text of the tag.
+     */
+    icon?: Image.ImageLike | undefined | null;
+    /**
+     * The text of the tag.
+     */
+    text: string;
+    /**
+     * Changes the text color to the provided color and sets a transparent background with the same color.
+     */
+    color?: Color.ColorLike | undefined | null;
+}
+
 declare interface TagListMembers {
     /**
      * A Tag in a {@link Detail.Metadata.TagList}.
@@ -6797,6 +6897,13 @@ declare interface TagListMembers {
     Item: typeof TagListItem;
 }
 
+declare interface TagListMembers_2 {
+    /**
+     * A Tag in a {@link List.Item.Detail.Metadata.TagList}.
+     */
+    Item: typeof TagListItem_2;
+}
+
 declare interface TagListProps {
     /**
      * The title shown above the item.
@@ -6808,6 +6915,17 @@ declare interface TagListProps {
     children: ReactNode;
 }
 
+declare interface TagListProps_2 {
+    /**
+     * The title shown above the item.
+     */
+    title: string;
+    /**
+     * The tags contained in the TagList.
+     */
+    children: ReactNode;
+}
+
 /**
  * See {@link Form.TagPicker}
  */

package/bin/ray

@@ -1,18 +1,59 @@
-#!/usr/bin/env bash
+#!/bin/bash
 
-DIR=$(dirname "${BASH_SOURCE[0]}")
-SYMLINK=$(readlink "${BASH_SOURCE[0]}")
-RESOLVED_DIR="$( cd -P "$( dirname "$DIR/$SYMLINK" )" >/dev/null 2>&1 && pwd )"
-
-if [ -z "$RESOLVED_DIR" ]; then
-	echo "Unable to determine CLI path from symlink: ${BASH_SOURCE[0]}"
+# Determine the path for dist folder
+# Using readlink -f to follow up any symlinks that will appear when using `npx`
+script_path=$(readlink -f "${BASH_SOURCE:-$0}")
+bin_dir=$(dirname $script_path)
+dist_dir=$(dirname $bin_dir)
+if [ -z "$bin_dir" ]; then
+	echo "Unable to determine CLI path from symlink: ${BASH_SOURCE-$0}"
 	exit 1
 fi
 
-ARCH_NAME="$(uname -m)"
-ARCH_DIR="x86"
-if [ "${ARCH_NAME}" = "arm64" ]; then
-  ARCH_DIR="arm64"
+# Read API version from package.json from current NPM, which will define the CLI version
+api_version=$(sed -n 's|.*"version": "\([^"]*\)".*|\1|p' < "$dist_dir/package.json")
+if [ -z "$api_version" ]; then
+    echo "Fail parsing version"
+    exit 1
+fi
+
+# CLI installation subroutine, using custom version and path for the CLI
+function install_cli { 
+	if ! curl -f -sL https://raycast.com/get-cli/ | VERSION="$api_version" INSTALL_PATH="$ray_path" bash; then
+		exit 1
+	fi
+}
+
+# Define the architecture directory in /dist folder to pick the right CLI version
+os="$(uname)"
+architecture="$(uname -m)"
+architecture_dir="x86"
+if [[ "${os}" = "Darwin" && "${architecture}" = "arm64" ]]; then
+	architecture_dir="arm64"
+elif [ "${os}" = "Linux" ]; then
+	architecture_dir="linux"
+fi
+
+# Define the path for CLI for current architecture
+ray_path=$bin_dir/$architecture_dir/ray
+
+# If there is no CLI for current architecture, download it
+if [ ! -f "$ray_path" ]; then
+	install_cli;
+else
+	# If version of the CLI for current architecture is outdated, re-download the CLI
+	ray_version=$($ray_path version)
+	if [ "$ray_version" != "$api_version" ]; then
+		install_cli;
+	fi
 fi
 
-"${RESOLVED_DIR}/${ARCH_DIR}/ray" "$@"
+# For npm-post-install script, we don't execute the CLI
+if [ "$1" == "npm-post-install" ]; then
+	exit 0
+fi
+
+# Execute the CLI passing all parameters to it
+file /usr/local
+
+$ray_path "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raycast/api",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "description": "Build extensions for Raycast with React and Node.js.",
   "author": "Raycast Technologies Ltd.",
   "homepage": "https://developers.raycast.com",
@@ -12,7 +12,10 @@
     "react": "18.1.0",
     "react-reconciler": "0.28.0"
   },
+  "scripts": {
+    "postinstall": "bin/ray npm-post-install"
+  },
   "bin": {
-    "ray": "./bin/ray"
+    "ray": "bin/ray"
   }
 }

package/types/index.d.ts

@@ -2109,6 +2109,10 @@ export declare interface Environment {
      * The name of the launched command, as specified in package.json
      */
     commandName: string;
+    /**
+     * The mode of the launched command, as specified in package.json
+     */
+    commandMode: "no-view" | "view" | "menu-bar";
     /**
      * The absolute path to the assets directory of the extension.
      *
@@ -2144,6 +2148,7 @@ export declare interface Environment {
  * console.log(`Raycast version: ${environment.raycastVersion}`);
  * console.log(`Extension name: ${environment.extensionName}`);
  * console.log(`Command name: ${environment.commandName}`);
+ * console.log(`Command mode: ${environment.commandMode}`);
  * console.log(`Assets path: ${environment.assetsPath}`);
  * console.log(`Support path: ${environment.supportPath}`);
  * console.log(`Is development mode: ${environment.isDevelopment}`);
@@ -2196,6 +2201,7 @@ export declare namespace Form {
     export type Value = FormValue_2;
     export type Values = FormValues_2;
     export type Props = FormProps_2;
+    export type ItemReference = FormItemRef;
     /**
      * An interface describing event in callbacks {@link Form.Item.Props.onFocus} and {@link Form.Item.Props.onBlur}
      */
@@ -3912,7 +3918,7 @@ declare interface GridMembers {
      * export default function Command() {
      *   return (
      *     <Grid>
-     *       <Grid.Item icon={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" />
+     *       <Grid.Item content={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" />
      *     </Grid>
      *   );
      * }
@@ -4121,6 +4127,7 @@ export declare enum Icon {
     BellDisabled = "bell-disabled-16",
     Bike = "bike-16",
     Binoculars = "binoculars-16",
+    Bird = "bird-16",
     BlankDocument = "blank-document-16",
     Bluetooth = "bluetooth-16",
     Boat = "boat-16",
@@ -4494,7 +4501,9 @@ export declare enum Icon {
     /** @deprecated Use {@link Icon.SpeakerOff} instead. */
     SpeakerSlash = "speaker-off-16",
     /** @deprecated Use {@link Icon.BlankDocument} instead. */
-    TextDocument = "blank-document-16"
+    TextDocument = "blank-document-16",
+    /** @deprecated Use {@link Icon.XMarkCircle} instead. */
+    XmarkCircle = "x-mark-circle-16"
 }
 
 /**
@@ -4851,10 +4860,25 @@ declare interface ItemProps_2 extends ActionsInterface {
 }
 
 declare interface ItemProps_3 {
+    /**
+     * The main title displayed for this item.
+     */
     title: string;
+    /**
+     * An optional icon for this item.
+     */
     icon?: Image.ImageLike;
+    /**
+     * A tooltip to display when the cursor hovers the item.
+     */
     tooltip?: string;
+    /**
+     * An action handler called when the user clicks the item.
+     */
     onAction?: () => void;
+    /**
+     * A shortcut used to invoke this item when its parent menu is open.
+     */
     shortcut?: Keyboard.Shortcut;
 }
 
@@ -4994,6 +5018,11 @@ export declare enum LaunchType {
  */
 declare const Link: FunctionComponent<LinkProps>;
 
+/**
+ * See {@link List.Item.Detail.Metadata.Link}
+ */
+declare const Link_2: FunctionComponent<LinkProps_2>;
+
 declare interface LinkProps {
     /**
      * The title shown above the item.
@@ -5009,6 +5038,21 @@ declare interface LinkProps {
     text: string;
 }
 
+declare interface LinkProps_2 {
+    /**
+     * The title shown above the item.
+     */
+    title: string;
+    /**
+     * The target of the link.
+     */
+    target: string;
+    /**
+     * The text value of the item.
+     */
+    text: string;
+}
+
 /**
  * Displays {@link List.Section} or {@link List.Item}, optionally {@link List.Dropdown}.
  *
@@ -5495,12 +5539,25 @@ declare interface MenuBarExtraMembers {
 
 declare interface MenuBarExtraProps {
     /**
+     * Indicates to Raycast that it should not unload the command, as it is still executing. If you set make use of `isLoading`, you need to make sure you set it to `false` at the end of the task you are executing (such as an API call), so Raycast can then unload the command.
      * @defaultValue `false`
      */
     isLoading?: boolean;
+    /**
+     * The string that is displayed in the menu bar.
+     */
     title?: string;
+    /**
+     * A tooltip to display when the cursor hovers the item in the menu bar.
+     */
     tooltip?: string;
+    /**
+     * The icon that is displayed in the menu bar.
+     */
     icon?: Image.ImageLike;
+    /**
+     * `MenuBarExtra.Item`s, `MenuBarExtra.Submenu`s, `MenuBarExtra.Separator` or a mix of either.
+     */
     children?: ReactNode;
 }
 
@@ -5562,6 +5619,10 @@ declare interface MetadataMembers_2 {
      * ```
      */
     Label: typeof Label_2;
+    /**
+     * An item to display a link.
+     */
+    Link: typeof Link_2;
     /**
      * A metadata item that shows a separator line. Use it for grouping and visually separating metadata items.
      *
@@ -5592,6 +5653,10 @@ declare interface MetadataMembers_2 {
      * ```
      */
     Separator: typeof Separator_3;
+    /**
+     * A list of {@link List.Item.Detail.Metadata.TagList.Item} displayed in a row.
+     */
+    TagList: typeof TagList_2;
 }
 
 declare interface MetadataProps {
@@ -6710,11 +6775,17 @@ declare interface SubmenuProps {
 }
 
 declare interface SubmenuProps_2 {
-    title: string | {
-        value: string;
-        tooltip: string;
-    };
+    /**
+     * The main title displayed for this submenu.
+     */
+    title: string;
+    /**
+     * An optional icon for this submenu.
+     */
     icon?: Image.ImageLike;
+    /**
+     * `MenuBarExtra.Item`s, `MenuBarExtra.Submenu`s, `MenuBarExtra.Separator` or a mix of either.
+     */
     children?: ReactNode;
 }
 
@@ -6761,8 +6832,12 @@ declare interface SubmitFormProps<T extends Form.Values> {
      * Callback that is triggered when the submit was submitted.
      * Use the handler to perform custom validation logic and call other Raycast API methods.
      * The handler receives a the values object containing the user input.
+     *
+     * @returns You can optionally return `false` to indicate that the submit action failed. Raycast will show some subtle feedback to the user that something went wrong. Pair it with the Form inputs' `validation` for a top-notch user experience.
+     *
+     * _If a user has the Accessibility setting 'Reduce Motion' enabled, Raycast won't show the feedback._
      */
-    onSubmit?: (input: T) => void;
+    onSubmit?: (input: T) => void | boolean | Promise<void | boolean>;
 }
 
 /**
@@ -6770,11 +6845,21 @@ declare interface SubmitFormProps<T extends Form.Values> {
  */
 declare const TagList: FunctionComponent<TagListProps> & TagListMembers;
 
+/**
+ * See {@link List.Item.Detail.Metadata.TagList}
+ */
+declare const TagList_2: FunctionComponent<TagListProps_2> & TagListMembers_2;
+
 /**
  * See {@link Detail.Metadata.TagList.Item}
  */
 declare const TagListItem: FunctionComponent<TagListItemProps>;
 
+/**
+ * See {@link Detail.Metadata.TagList.Item}
+ */
+declare const TagListItem_2: FunctionComponent<TagListItemProps_2>;
+
 declare interface TagListItemProps {
     /**
      * An optional icon in front of the text of the tag.
@@ -6790,6 +6875,21 @@ declare interface TagListItemProps {
     color?: Color.ColorLike | undefined | null;
 }
 
+declare interface TagListItemProps_2 {
+    /**
+     * An optional icon in front of the text of the tag.
+     */
+    icon?: Image.ImageLike | undefined | null;
+    /**
+     * The text of the tag.
+     */
+    text: string;
+    /**
+     * Changes the text color to the provided color and sets a transparent background with the same color.
+     */
+    color?: Color.ColorLike | undefined | null;
+}
+
 declare interface TagListMembers {
     /**
      * A Tag in a {@link Detail.Metadata.TagList}.
@@ -6797,6 +6897,13 @@ declare interface TagListMembers {
     Item: typeof TagListItem;
 }
 
+declare interface TagListMembers_2 {
+    /**
+     * A Tag in a {@link List.Item.Detail.Metadata.TagList}.
+     */
+    Item: typeof TagListItem_2;
+}
+
 declare interface TagListProps {
     /**
      * The title shown above the item.
@@ -6808,6 +6915,17 @@ declare interface TagListProps {
     children: ReactNode;
 }
 
+declare interface TagListProps_2 {
+    /**
+     * The title shown above the item.
+     */
+    title: string;
+    /**
+     * The tags contained in the TagList.
+     */
+    children: ReactNode;
+}
+
 /**
  * See {@link Form.TagPicker}
  */