@raycast/api 1.39.2 → 1.40.0

package/api.d.ts

@@ -1128,7 +1128,7 @@ declare interface ConvenienceActions {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [name, setName] = useState<string>();
+     *   const [name, setName] = useState<string>("");
      *
      *   return (
      *     <Form
@@ -1352,7 +1352,7 @@ declare interface DatePickerMembers {
     Type: typeof DatePickerType;
 }
 
-declare interface DatePickerProps extends FormItemProps_2<Date> {
+declare interface DatePickerProps extends FormItemProps_2<Date | null> {
     /**
      * Indicates what types of date components can be picked
      *
@@ -1689,6 +1689,13 @@ declare interface DropdownItemProps {
      * A optional icon displayed for the item.
      */
     icon?: Image.ImageLike;
+    /**
+     * An optional property used for providing additional indexable strings for search.
+     * When filtering the items in Raycast, the keywords will be searched in addition to the title.
+     *
+     * @defaultValue The title of its section if any
+     */
+    keywords?: string[];
 }
 
 declare interface DropdownItemProps_2 {
@@ -1705,6 +1712,13 @@ declare interface DropdownItemProps_2 {
      * An optional icon displayed for the item.
      */
     icon?: Image.ImageLike | undefined | null;
+    /**
+     * An optional property used for providing additional indexable strings for search.
+     * When filtering the items in Raycast, the keywords will be searched in addition to the title.
+     *
+     * @defaultValue The title of its section if any
+     */
+    keywords?: string[];
 }
 
 declare interface DropdownItemProps_3 {
@@ -1721,6 +1735,13 @@ declare interface DropdownItemProps_3 {
      * An optional icon displayed for the item.
      */
     icon?: Image.ImageLike | undefined | null;
+    /**
+     * An optional property used for providing additional indexable strings for search.
+     * When filtering the items in Raycast, the keywords will be searched in addition to the title.
+     *
+     * @defaultValue The title of its section if any
+     */
+    keywords?: string[];
 }
 
 declare interface DropdownMembers {
@@ -3132,7 +3153,7 @@ declare interface FormMembers {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [date, setDate] = useState<Date>();
+     *   const [date, setDate] = useState<Date | null>(null);
      *
      *   return (
      *     <Form
@@ -3162,13 +3183,7 @@ declare interface FormMembers {
      *
      * export default function Command() {
      *   return (
-     *     <Form
-     *       actions={
-     *         <ActionPanel>
-     *           <Action.SubmitForm title="Submit" onSubmit={(values) => console.log(values)} />
-     *         </ActionPanel>
-     *       }
-     *     >
+     *     <Form>
      *       <Form.Description title="Import / Export" text="Exporting will back-up your preferences, quicklinks, snippets, floating notes, script-command folder paths, aliases, hotkeys, favorites and other data." />
      *     </Form>
      *   );
@@ -3273,7 +3288,7 @@ declare interface FormMembers {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [password, setPassword] = useState<string>();
+     *   const [password, setPassword] = useState<string>("");
      *
      *   return (
      *     <Form
@@ -3300,13 +3315,7 @@ declare interface FormMembers {
      *
      * export default function Command() {
      *   return (
-     *     <Form
-     *       actions={
-     *         <ActionPanel>
-     *           <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
-     *         </ActionPanel>
-     *       }
-     *     >
+     *     <Form>
      *       <Form.TextField id="textfield" />
      *       <Form.Separator />
      *       <Form.TextArea id="textarea" />
@@ -3413,7 +3422,7 @@ declare interface FormMembers {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [description, setDescription] = useState<string>();
+     *   const [description, setDescription] = useState<string>("");
      *
      *   return (
      *     <Form
@@ -3462,7 +3471,7 @@ declare interface FormMembers {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [name, setName] = useState<string>();
+     *   const [name, setName] = useState<string>("");
      *
      *   return (
      *     <Form
@@ -3583,7 +3592,7 @@ export declare interface FormValues extends Form.Values {
  *
  * @example
  * ```typescript
- * import { Form, Action } from "@raycast/api";
+ * import { Form, Action, ActionPanel } from "@raycast/api";
  *
  * interface Values {
  *   todo: string;
@@ -4001,6 +4010,10 @@ declare interface GridMembers {
 }
 
 declare interface GridProps extends ActionsInterface, NavigationChildInterface {
+    /**
+     * A reference to an {@link ActionPanel}. It will only be shown when there aren't any children.
+     */
+    actions?: ReactNode;
     /**
      * Grid sections or items. If {@link Grid.Item} elements are specified, a default section is automatically created.
      */
@@ -4725,6 +4738,34 @@ declare type ItemAccessory = ({
     tooltip?: string | undefined | null;
 };
 
+/**
+ * An interface describing Action events in callbacks
+ *
+ * @example
+ * ```typescript
+ *import { MenuBarExtra } from "@raycast/api";
+ *
+ *export default function Command() {
+ *  return (
+ *    <MenuBarExtra>
+ *      <MenuBarExtra.Item
+ *        title="Log Action Event Type"
+ *        onAction={(event: MenuBarExtra.ActionEvent) => console.log("Action Event Type", event.type)} />
+ *    <MenuBarExtra>
+ *  );
+ *}
+ * ```
+ */
+declare interface ItemActionEvent {
+    /**
+     * A type of the action event
+     *
+     * * `left-click` is a left mouse click on the {@link MenuBarExtra.Item} or a {@link Keyboard.Shortcut}
+     * * `right-click` is a right mouse click on the {@link MenuBarExtra.Item}
+     */
+    type: "left-click" | "right-click";
+}
+
 declare interface ItemMembers {
     /**
      * A Detail view that will be shown in the right-hand-side of the List.
@@ -4875,7 +4916,7 @@ declare interface ItemProps_3 {
     /**
      * An action handler called when the user clicks the item.
      */
-    onAction?: () => void;
+    onAction?: (event: ItemActionEvent) => void;
     /**
      * A shortcut used to invoke this item when its parent menu is open.
      */
@@ -5326,6 +5367,10 @@ export declare interface ListProps extends List.Props {
 }
 
 declare interface ListProps_2 extends ActionsInterface, NavigationChildInterface {
+    /**
+     * A reference to an {@link ActionPanel}. It will only be shown when there aren't any children.
+     */
+    actions?: ReactNode;
     /**
      * List sections or items. If {@link List.Item} elements are specified, a default section is automatically created.
      */
@@ -5525,15 +5570,149 @@ export declare type LocalStorageValue = LocalStorage.Value;
 export declare interface LocalStorageValues extends LocalStorage.Values {
 }
 
+/**
+ * Adds an item to the menu bar, optionally with a menu attached in case its `children` prop is non-empty.
+ *
+ * @remarks
+ * `menu-bar` commands don't always need to return a `MenuBarExtra`. Sometimes it makes sense to remove an item from the
+ * menu bar, in which case you can write your command logic to return `null` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Icon, MenuBarExtra, open } from "@raycast/api";
+ * import { useBookmarks } from "./hooks";
+ *
+ * export default function Command() {
+ *   const [newBookmarks, archivedBookmarks, isLoading] = useBookmarks();
+ *
+ *   return (
+ *     <MenuBarExtra icon={Icon.Bookmark} isLoading={isLoading}>
+ *       <MenuBarExtra.Item title="New" />
+ *       {newBookmarks.map((bookmark) => (
+ *         <MenuBarExtra.Item key={bookmark.url} title={bookmark.name} onAction={() => open(bookmark.url)} />
+ *       ))}
+ *       <MenuBarExtra.Separator />
+ *       <MenuBarExtra.Item title="Archived" />
+ *       {archivedBookmarks.map((bookmark) => (
+ *         <MenuBarExtra.Item key={bookmark.url} title={bookmark.name} onAction={() => open(bookmark.url)} />
+ *       ))}
+ *     </MenuBarExtra>
+ *   );
+ * }
+ * ```
+ */
 export declare const MenuBarExtra: FunctionComponent<MenuBarExtraProps> & MenuBarExtraMembers;
 
 export declare namespace MenuBarExtra {
     export type Props = MenuBarExtraProps;
+    /**
+     * An interface describing Action events in callbacks
+     *
+     * @example
+     * ```typescript
+     *import { MenuBarExtra } from "@raycast/api";
+     *
+     *export default function Command() {
+     *  return (
+     *    <MenuBarExtra>
+     *      <MenuBarExtra.Item
+     *        title="Log Action Event Type"
+     *        onAction={(event: MenuBarExtra.ActionEvent) => console.log("Action Event Type", event.type)} />
+     *    <MenuBarExtra>
+     *  );
+     *}
+     * ```
+     */
+    export type ActionEvent = ItemActionEvent;
 }
 
 declare interface MenuBarExtraMembers {
+    /**
+     * An item in the {@link MenuBarExtra} or {@link MenuBarExtra.Submenu}.
+     *
+     * @remarks
+     * An item that only provides only a `title` (and optionally `icon`) prop will be rendered as disabled. Use this to create section titles.
+     *
+     * @remarks
+     * An item that provides an `onAction` prop alongside `title` (and optionally `icon`) will _not_ be rendered as
+     * disabled. When users click this item in the menu bar, the action handler will be executed.
+     *
+     * @example
+     * ```typescript
+     * import { MenuBarExtra } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <MenuBarExtra icon="https://github.githubassets.com/favicons/favicon.png" tooltip="Your Pull Requests">
+     *       <MenuBarExtra.Item title="Unseen" />
+     *       <MenuBarExtra.Item
+     *         title="Example Unseen Pull Request"
+     *         onAction={() => {
+     *           console.log("unseen pull request clicked");
+     *         }}
+     *       />
+     *     </MenuBarExtra>
+     *   );
+     * }
+     * ```
+     */
     Item: typeof Item_3;
+    /**
+     * A visual separator between two items of type {@link MenuBarExtra.Item} or {@link MenuBarExtra.Submenu}.
+     *
+     * @example
+     * ```typescript
+     * import { MenuBarExtra } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <MenuBarExtra icon="https://github.githubassets.com/favicons/favicon.png" tooltip="Your Pull Requests">
+     *       <MenuBarExtra.Item title="Item 1" />
+     *       <MenuBarExtra.Separator />
+     *       <MenuBarExtra.Item title="Item 2" />
+     *       <MenuBarExtra.Separator />
+     *       <MenuBarExtra.Submenu title="Submenu 1">
+     *         <MenuBarExtra.Item title="Submenu 1 Item 1" />
+     *       </MenuBarExtra.Submenu>
+     *       <MenuBarExtra.Separator />
+     *       <MenuBarExtra.Submenu title="Submenu 2">
+     *         <MenuBarExtra.Item title="Submenu 2 Item 1" />
+     *       </MenuBarExtra.Submenu>
+     *     </MenuBarExtra>
+     *   );
+     * }
+     * ```
+     */
     Separator: typeof Separator_4;
+    /**
+     * A group of related {@link MenuBarExtra.Item} or {@link MenuBarExtra.Submenu}.
+     *
+     * @remarks
+     * {@link MenuBarExtra.Submenu}s reveal their items when people interact with them. They're a good way to group items
+     * that naturally belong together, but keep in mind that submenus add complexity to your interface - so use them
+     * sparingly!
+     *
+     * @example
+     * ```typescript
+     * import { MenuBarExtra } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <MenuBarExtra icon="https://github.githubassets.com/favicons/favicon.png" tooltip="Your Pull Requests">
+     *       <MenuBarExtra.Submenu title="Submenu With Item">
+     *         <MenuBarExtra.Item title="Item" />
+     *       </MenuBarExtra.Submenu>
+     *       <MenuBarExtra.Submenu title="Disabled Submenu" />
+     *       <MenuBarExtra.Submenu title="Submenu With Submenu">
+     *         <MenuBarExtra.Submenu title="Child Submenu">
+     *           <MenuBarExtra.Item title="Item" />
+     *         </MenuBarExtra.Submenu>
+     *       </MenuBarExtra.Submenu>
+     *     </MenuBarExtra>
+     *   );
+     * }
+     * ```
+     */
     Submenu: typeof Submenu_2;
 }
 
@@ -5820,8 +5999,11 @@ export declare namespace OAuth {
     export enum RedirectMethod {
         /**
          * Use this type for a redirect back to the Raycast website, which will then open the extension.
-         * In the OAuth app, configure either `https://raycast.com/redirect` or `https://raycast.com/redirect?packageName=Extension`
-         * (For example, Twitter would accept the former, while Spotify requires the query parameter.)
+         * In the OAuth app, configure `https://raycast.com/redirect?packageName=Extension`
+         * (This is a static redirect URL for all extensions.)
+         * If the provider does not accept query parameters in redirect URLs, you can alternatively use `https://raycast.com/redirect/extension`
+         * and then customize the {@link OAuth.AuthorizationRequest} via its `extraParameters` property. For example add:
+         *  `extraParameters: { "redirect_uri": "https://raycast.com/redirect/extension" }`
          */
         Web = "web",
         /**

package/bin/ray

@@ -11,7 +11,7 @@ while [ -L "$source" ]; do
   [[ $source != /* ]] && source=$dir/$source
 done
 bin_dir=$( cd -P "$( dirname "$source" )" >/dev/null 2>&1 && pwd )
-dist_dir=$(dirname $bin_dir)
+dist_dir=$(dirname "$bin_dir")
 
 if [ -z "$bin_dir" ]; then
 	echo "Unable to determine CLI path for source: ${BASH_SOURCE:-$0}"
@@ -43,14 +43,14 @@ elif [ "${os}" = "Linux" ]; then
 fi
 
 # Define the path for CLI for current architecture
-ray_path=$bin_dir/$architecture_dir/ray
+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)
+	ray_version=$("$ray_path" version)
 	if [ "$ray_version" != "$api_version" ]; then
 		install_cli;
 	fi
@@ -62,4 +62,4 @@ if [ "$1" == "npm-post-install" ]; then
 fi
 
 # Execute the CLI passing all parameters to it
-$ray_path "$@"
+"$ray_path" "$@"

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@raycast/api",
-  "version": "1.39.2",
+  "version": "1.40.0",
   "description": "Build extensions for Raycast with React and Node.js.",
   "author": "Raycast Technologies Ltd.",
   "homepage": "https://developers.raycast.com",
+  "repository": {
+    "url": "https://github.com/raycast/extensions"
+  },
   "license": "MIT",
   "types": "types/index.d.ts",
   "dependencies": {
@@ -12,6 +15,18 @@
     "react": "18.1.0",
     "react-reconciler": "0.28.0"
   },
+  "peerDependencies": {
+    "@types/node": "16.10.3",
+    "@types/react": "18.0.9"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    },
+    "@types/react": {
+      "optional": true
+    }
+  },
   "scripts": {
     "postinstall": "bin/ray npm-post-install"
   },

package/types/index.d.ts

@@ -1128,7 +1128,7 @@ declare interface ConvenienceActions {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [name, setName] = useState<string>();
+     *   const [name, setName] = useState<string>("");
      *
      *   return (
      *     <Form
@@ -1352,7 +1352,7 @@ declare interface DatePickerMembers {
     Type: typeof DatePickerType;
 }
 
-declare interface DatePickerProps extends FormItemProps_2<Date> {
+declare interface DatePickerProps extends FormItemProps_2<Date | null> {
     /**
      * Indicates what types of date components can be picked
      *
@@ -1689,6 +1689,13 @@ declare interface DropdownItemProps {
      * A optional icon displayed for the item.
      */
     icon?: Image.ImageLike;
+    /**
+     * An optional property used for providing additional indexable strings for search.
+     * When filtering the items in Raycast, the keywords will be searched in addition to the title.
+     *
+     * @defaultValue The title of its section if any
+     */
+    keywords?: string[];
 }
 
 declare interface DropdownItemProps_2 {
@@ -1705,6 +1712,13 @@ declare interface DropdownItemProps_2 {
      * An optional icon displayed for the item.
      */
     icon?: Image.ImageLike | undefined | null;
+    /**
+     * An optional property used for providing additional indexable strings for search.
+     * When filtering the items in Raycast, the keywords will be searched in addition to the title.
+     *
+     * @defaultValue The title of its section if any
+     */
+    keywords?: string[];
 }
 
 declare interface DropdownItemProps_3 {
@@ -1721,6 +1735,13 @@ declare interface DropdownItemProps_3 {
      * An optional icon displayed for the item.
      */
     icon?: Image.ImageLike | undefined | null;
+    /**
+     * An optional property used for providing additional indexable strings for search.
+     * When filtering the items in Raycast, the keywords will be searched in addition to the title.
+     *
+     * @defaultValue The title of its section if any
+     */
+    keywords?: string[];
 }
 
 declare interface DropdownMembers {
@@ -3132,7 +3153,7 @@ declare interface FormMembers {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [date, setDate] = useState<Date>();
+     *   const [date, setDate] = useState<Date | null>(null);
      *
      *   return (
      *     <Form
@@ -3162,13 +3183,7 @@ declare interface FormMembers {
      *
      * export default function Command() {
      *   return (
-     *     <Form
-     *       actions={
-     *         <ActionPanel>
-     *           <Action.SubmitForm title="Submit" onSubmit={(values) => console.log(values)} />
-     *         </ActionPanel>
-     *       }
-     *     >
+     *     <Form>
      *       <Form.Description title="Import / Export" text="Exporting will back-up your preferences, quicklinks, snippets, floating notes, script-command folder paths, aliases, hotkeys, favorites and other data." />
      *     </Form>
      *   );
@@ -3273,7 +3288,7 @@ declare interface FormMembers {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [password, setPassword] = useState<string>();
+     *   const [password, setPassword] = useState<string>("");
      *
      *   return (
      *     <Form
@@ -3300,13 +3315,7 @@ declare interface FormMembers {
      *
      * export default function Command() {
      *   return (
-     *     <Form
-     *       actions={
-     *         <ActionPanel>
-     *           <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
-     *         </ActionPanel>
-     *       }
-     *     >
+     *     <Form>
      *       <Form.TextField id="textfield" />
      *       <Form.Separator />
      *       <Form.TextArea id="textarea" />
@@ -3413,7 +3422,7 @@ declare interface FormMembers {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [description, setDescription] = useState<string>();
+     *   const [description, setDescription] = useState<string>("");
      *
      *   return (
      *     <Form
@@ -3462,7 +3471,7 @@ declare interface FormMembers {
      * import { useState } from "react";
      *
      * export default function Command() {
-     *   const [name, setName] = useState<string>();
+     *   const [name, setName] = useState<string>("");
      *
      *   return (
      *     <Form
@@ -3583,7 +3592,7 @@ export declare interface FormValues extends Form.Values {
  *
  * @example
  * ```typescript
- * import { Form, Action } from "@raycast/api";
+ * import { Form, Action, ActionPanel } from "@raycast/api";
  *
  * interface Values {
  *   todo: string;
@@ -4001,6 +4010,10 @@ declare interface GridMembers {
 }
 
 declare interface GridProps extends ActionsInterface, NavigationChildInterface {
+    /**
+     * A reference to an {@link ActionPanel}. It will only be shown when there aren't any children.
+     */
+    actions?: ReactNode;
     /**
      * Grid sections or items. If {@link Grid.Item} elements are specified, a default section is automatically created.
      */
@@ -4725,6 +4738,34 @@ declare type ItemAccessory = ({
     tooltip?: string | undefined | null;
 };
 
+/**
+ * An interface describing Action events in callbacks
+ *
+ * @example
+ * ```typescript
+ *import { MenuBarExtra } from "@raycast/api";
+ *
+ *export default function Command() {
+ *  return (
+ *    <MenuBarExtra>
+ *      <MenuBarExtra.Item
+ *        title="Log Action Event Type"
+ *        onAction={(event: MenuBarExtra.ActionEvent) => console.log("Action Event Type", event.type)} />
+ *    <MenuBarExtra>
+ *  );
+ *}
+ * ```
+ */
+declare interface ItemActionEvent {
+    /**
+     * A type of the action event
+     *
+     * * `left-click` is a left mouse click on the {@link MenuBarExtra.Item} or a {@link Keyboard.Shortcut}
+     * * `right-click` is a right mouse click on the {@link MenuBarExtra.Item}
+     */
+    type: "left-click" | "right-click";
+}
+
 declare interface ItemMembers {
     /**
      * A Detail view that will be shown in the right-hand-side of the List.
@@ -4875,7 +4916,7 @@ declare interface ItemProps_3 {
     /**
      * An action handler called when the user clicks the item.
      */
-    onAction?: () => void;
+    onAction?: (event: ItemActionEvent) => void;
     /**
      * A shortcut used to invoke this item when its parent menu is open.
      */
@@ -5326,6 +5367,10 @@ export declare interface ListProps extends List.Props {
 }
 
 declare interface ListProps_2 extends ActionsInterface, NavigationChildInterface {
+    /**
+     * A reference to an {@link ActionPanel}. It will only be shown when there aren't any children.
+     */
+    actions?: ReactNode;
     /**
      * List sections or items. If {@link List.Item} elements are specified, a default section is automatically created.
      */
@@ -5525,15 +5570,149 @@ export declare type LocalStorageValue = LocalStorage.Value;
 export declare interface LocalStorageValues extends LocalStorage.Values {
 }
 
+/**
+ * Adds an item to the menu bar, optionally with a menu attached in case its `children` prop is non-empty.
+ *
+ * @remarks
+ * `menu-bar` commands don't always need to return a `MenuBarExtra`. Sometimes it makes sense to remove an item from the
+ * menu bar, in which case you can write your command logic to return `null` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Icon, MenuBarExtra, open } from "@raycast/api";
+ * import { useBookmarks } from "./hooks";
+ *
+ * export default function Command() {
+ *   const [newBookmarks, archivedBookmarks, isLoading] = useBookmarks();
+ *
+ *   return (
+ *     <MenuBarExtra icon={Icon.Bookmark} isLoading={isLoading}>
+ *       <MenuBarExtra.Item title="New" />
+ *       {newBookmarks.map((bookmark) => (
+ *         <MenuBarExtra.Item key={bookmark.url} title={bookmark.name} onAction={() => open(bookmark.url)} />
+ *       ))}
+ *       <MenuBarExtra.Separator />
+ *       <MenuBarExtra.Item title="Archived" />
+ *       {archivedBookmarks.map((bookmark) => (
+ *         <MenuBarExtra.Item key={bookmark.url} title={bookmark.name} onAction={() => open(bookmark.url)} />
+ *       ))}
+ *     </MenuBarExtra>
+ *   );
+ * }
+ * ```
+ */
 export declare const MenuBarExtra: FunctionComponent<MenuBarExtraProps> & MenuBarExtraMembers;
 
 export declare namespace MenuBarExtra {
     export type Props = MenuBarExtraProps;
+    /**
+     * An interface describing Action events in callbacks
+     *
+     * @example
+     * ```typescript
+     *import { MenuBarExtra } from "@raycast/api";
+     *
+     *export default function Command() {
+     *  return (
+     *    <MenuBarExtra>
+     *      <MenuBarExtra.Item
+     *        title="Log Action Event Type"
+     *        onAction={(event: MenuBarExtra.ActionEvent) => console.log("Action Event Type", event.type)} />
+     *    <MenuBarExtra>
+     *  );
+     *}
+     * ```
+     */
+    export type ActionEvent = ItemActionEvent;
 }
 
 declare interface MenuBarExtraMembers {
+    /**
+     * An item in the {@link MenuBarExtra} or {@link MenuBarExtra.Submenu}.
+     *
+     * @remarks
+     * An item that only provides only a `title` (and optionally `icon`) prop will be rendered as disabled. Use this to create section titles.
+     *
+     * @remarks
+     * An item that provides an `onAction` prop alongside `title` (and optionally `icon`) will _not_ be rendered as
+     * disabled. When users click this item in the menu bar, the action handler will be executed.
+     *
+     * @example
+     * ```typescript
+     * import { MenuBarExtra } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <MenuBarExtra icon="https://github.githubassets.com/favicons/favicon.png" tooltip="Your Pull Requests">
+     *       <MenuBarExtra.Item title="Unseen" />
+     *       <MenuBarExtra.Item
+     *         title="Example Unseen Pull Request"
+     *         onAction={() => {
+     *           console.log("unseen pull request clicked");
+     *         }}
+     *       />
+     *     </MenuBarExtra>
+     *   );
+     * }
+     * ```
+     */
     Item: typeof Item_3;
+    /**
+     * A visual separator between two items of type {@link MenuBarExtra.Item} or {@link MenuBarExtra.Submenu}.
+     *
+     * @example
+     * ```typescript
+     * import { MenuBarExtra } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <MenuBarExtra icon="https://github.githubassets.com/favicons/favicon.png" tooltip="Your Pull Requests">
+     *       <MenuBarExtra.Item title="Item 1" />
+     *       <MenuBarExtra.Separator />
+     *       <MenuBarExtra.Item title="Item 2" />
+     *       <MenuBarExtra.Separator />
+     *       <MenuBarExtra.Submenu title="Submenu 1">
+     *         <MenuBarExtra.Item title="Submenu 1 Item 1" />
+     *       </MenuBarExtra.Submenu>
+     *       <MenuBarExtra.Separator />
+     *       <MenuBarExtra.Submenu title="Submenu 2">
+     *         <MenuBarExtra.Item title="Submenu 2 Item 1" />
+     *       </MenuBarExtra.Submenu>
+     *     </MenuBarExtra>
+     *   );
+     * }
+     * ```
+     */
     Separator: typeof Separator_4;
+    /**
+     * A group of related {@link MenuBarExtra.Item} or {@link MenuBarExtra.Submenu}.
+     *
+     * @remarks
+     * {@link MenuBarExtra.Submenu}s reveal their items when people interact with them. They're a good way to group items
+     * that naturally belong together, but keep in mind that submenus add complexity to your interface - so use them
+     * sparingly!
+     *
+     * @example
+     * ```typescript
+     * import { MenuBarExtra } from "@raycast/api";
+     *
+     * export default function Command() {
+     *   return (
+     *     <MenuBarExtra icon="https://github.githubassets.com/favicons/favicon.png" tooltip="Your Pull Requests">
+     *       <MenuBarExtra.Submenu title="Submenu With Item">
+     *         <MenuBarExtra.Item title="Item" />
+     *       </MenuBarExtra.Submenu>
+     *       <MenuBarExtra.Submenu title="Disabled Submenu" />
+     *       <MenuBarExtra.Submenu title="Submenu With Submenu">
+     *         <MenuBarExtra.Submenu title="Child Submenu">
+     *           <MenuBarExtra.Item title="Item" />
+     *         </MenuBarExtra.Submenu>
+     *       </MenuBarExtra.Submenu>
+     *     </MenuBarExtra>
+     *   );
+     * }
+     * ```
+     */
     Submenu: typeof Submenu_2;
 }
 
@@ -5820,8 +5999,11 @@ export declare namespace OAuth {
     export enum RedirectMethod {
         /**
          * Use this type for a redirect back to the Raycast website, which will then open the extension.
-         * In the OAuth app, configure either `https://raycast.com/redirect` or `https://raycast.com/redirect?packageName=Extension`
-         * (For example, Twitter would accept the former, while Spotify requires the query parameter.)
+         * In the OAuth app, configure `https://raycast.com/redirect?packageName=Extension`
+         * (This is a static redirect URL for all extensions.)
+         * If the provider does not accept query parameters in redirect URLs, you can alternatively use `https://raycast.com/redirect/extension`
+         * and then customize the {@link OAuth.AuthorizationRequest} via its `extraParameters` property. For example add:
+         *  `extraParameters: { "redirect_uri": "https://raycast.com/redirect/extension" }`
          */
         Web = "web",
         /**