shortcutkit 0.7.0 → 1.0.0

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import { type PlistValue } from "./plist.js";
 import { type ActionDefinition } from "./definitions.js";
 import { ACTIONS } from "./generated/actions.js";
 import type { ActionId, MetaParams, ParamTypes } from "./generated/actions.js";
-import type { Attachment, Picker, TokenString, Value } from "./values.js";
-export { actions, ACTIONS, PARAM_KINDS, type ActionId, type ActionKey, type ParamKey, type ParamTypes, type MetaParams } from "./generated/actions.js";
+import type { AskAttachment, Attachment, ConditionSubject, TokenString, Value } from "./values.js";
+export { actions, ACTIONS, PARAM_KINDS, PARAM_CHOICES, PARAM_VARIABLE_TYPES, type ActionId, type ActionKey, type ParamKey, type ParamTypes, type MetaParams } from "./generated/actions.js";
 export type { PlistValue } from "./plist.js";
 export type * from "./values.js";
 export { getDefinition, allDefinitions, type ActionDefinition, type ParameterDefinition, type Localized } from "./definitions.js";
@@ -11,22 +11,23 @@ export { provenance, type Provenance } from "./provenance.js";
 export type * from "./generated/params.js";
 /** Parameters accepted for an identifier: typed per key for built-in actions, open for anything else. */
 export type ParamsFor<I extends string> = I extends ActionId ? Partial<ParamTypes[I] & MetaParams> : Record<string, Value>;
+/** An action as `action()` returns it; pass it to `ref()` to use its output. */
 export type Action = {
     WFWorkflowActionIdentifier: string;
     WFWorkflowActionParameters: Record<string, Value>;
     outputName?: string;
     outputTypes?: readonly string[];
 };
-/** Content types an action's output can be (`WFStringContentItem`, `NSURL`, an App Intents entity, …). Shortcuts coerces between many of them at run time, so this describes, it does not restrict. */
+/** Content types an action's output can be (`WFStringContentItem`, `NSURL`, an App Intents entity, …). Shortcuts converts between many of them at run time, so this is a description, not a restriction. */
 export type OutputTypes<I extends ActionId> = (typeof ACTIONS)[I]["outputTypes"];
-/** What the catalogue knows about an identifier: built-in or App Intent, engine definition or not. */
+/** What the catalog knows about an identifier, built-in or App Intent. */
 export type CatalogEntry = {
     identifier: string;
     /** Display name, as the editor shows it. */
     name: string;
     /** Parameter keys the action accepts, in the editor's order. */
     params: readonly string[];
-    /** Value kind per key: bool, number, string, text, picker, plainString, plainNumber, dictionary, quantity, filter, any. */
+    /** Value kind per key: bool, number, string, text, picker, subject, plainString, plainNumber, dictionary, quantity, filter, any. */
     kinds: Record<string, string>;
     /** Output name, or null when the action produces nothing. */
     output: string | null;
@@ -38,8 +39,8 @@ export type CatalogEntry = {
     definition?: ActionDefinition;
 };
 /**
- * Look up any catalogue identifier, built-in or App Intent. getDefinition() only knows built-ins
- * (App Intents have no engine definition); this covers both with the same shape.
+ * Look up any catalog identifier, built-in or App Intent. Unlike getDefinition(), which knows
+ * only built-ins, this covers both in one shape.
  */
 export declare function getAction(identifier: string): CatalogEntry | undefined;
 /** Names the app that provides an App Intents action; written as the AppIntentDescriptor parameter. */
@@ -49,7 +50,7 @@ export type AppIntentDescriptor = {
     TeamIdentifier: string;
     AppIntentIdentifier: string;
 };
-/** WFWorkflowIcon.backgroundColorValue for palette colors 0-14, unsigned as the plist stores it. */
+/** The icon palette, in picker order, as the file stores each color. */
 export declare const ICON_COLORS: {
     readonly Red: 4282601983;
     readonly DarkOrange: 4251333119;
@@ -69,7 +70,7 @@ export declare const ICON_COLORS: {
 };
 export type IconColor = keyof typeof ICON_COLORS;
 export declare const DEFAULT_GLYPH = 61440;
-/** Legacy WFCondition codes. Marked (v) = verified on this Mac or in Apple's gallery; others follow community docs. */
+/** If condition codes. less_than, greater_than, contains, has_any_value, and has_no_value are verified against the engine or Apple's files; the rest follow community documentation. */
 export declare const CONDITION: {
     readonly less_than: 0;
     readonly less_or_equal: 1;
@@ -87,52 +88,87 @@ export declare const CONDITION: {
 };
 export type Condition = keyof typeof CONDITION;
 /** Reference another action's output. */
-export declare const ref: (action: Action, outputName?: string) => Attachment;
-export declare const variable: (name: string) => Attachment;
-export declare const shortcutInput: () => Attachment;
-export declare const clipboard: () => Attachment;
-export declare const currentDate: () => Attachment;
-export declare const ask: (prompt?: string) => Attachment;
-/** Wrap an attachment for WFVariablePickerParameter keys (Repeat with Each, If). */
-export declare const picker: (a: Attachment) => Picker;
-/** A WFTextTokenString: strings and attachments interleaved; each attachment becomes U+FFFC. */
+export declare const ref: (action: Action, outputName?: string) => Attachment<"ActionOutput">;
+/** A named variable, as set by Set Variable or Add to Variable. */
+export declare const variable: (name: string) => Attachment<"Variable">;
+/** The shortcut's input, from the share sheet, Quick Actions, or Run Shortcut. */
+export declare const shortcutInput: () => Attachment<"ExtensionInput">;
+/** The clipboard's contents. */
+export declare const clipboard: () => Attachment<"Clipboard">;
+/** The date and time the shortcut runs. */
+export declare const currentDate: () => Attachment<"CurrentDate">;
+/** A value the user is asked for each time the shortcut runs. */
+export declare const ask: (prompt?: string) => AskAttachment;
+/** Device Details (name, model, OS version, …); the app usually adds a property aggrandizement. */
+export declare const deviceDetails: () => Attachment<"DeviceDetails">;
+/** The app the shortcut was run from. */
+export declare const currentApp: () => Attachment<"CurrentApp">;
+/** The If-subject form of a reference. `if()` and `action()` apply it for you. */
+export declare const subject: (a: Attachment) => ConditionSubject;
+/** @deprecated Misnamed: this produces the If-subject form. Pass a bare `ref()` to variable-picker parameters; use `subject()` for If. */
+export declare const picker: (a: Attachment) => ConditionSubject;
+/** The current item inside a Repeat with Each block. */
+export declare const repeatItem: () => Attachment<"Variable">;
+/** The current index (1-based) inside a Repeat block. */
+export declare const repeatIndex: () => Attachment<"Variable">;
+/** Text with references in it: `text("Hello, ", ref(name), "!")`. */
 export declare function text(...parts: Array<string | number | Attachment>): TokenString;
+/** Where a shortcut is offered beyond the app: `ActionExtension` is the share sheet, `QuickActions` the Finder and Services menus, `MenuBar`, `NCWidget`, `WatchKit`, `Sleep`, `ReceivesOnScreenContent`. */
+export type WorkflowType = "ActionExtension" | "QuickActions" | "MenuBar" | "NCWidget" | "WatchKit" | "Sleep" | "ReceivesOnScreenContent";
 export interface ShortcutOptions {
+    /** Icon color: a palette name (`"Teal"`) or a raw value. Default `"Blue"`. */
     color?: IconColor | number;
+    /** Icon glyph, a codepoint from Shortcuts' icon font. Default 61440. */
     glyph?: number;
+    /** Content item classes accepted as input (`WFSafariWebPageContentItem`, `WFURLContentItem`, …); what the share sheet offers this shortcut for. */
     inputClasses?: string[];
+    /** Surfaces the shortcut appears in (`WFWorkflowTypes`); `["ActionExtension"]` puts it in the share sheet. Default none. */
+    types?: WorkflowType[];
 }
+/** A shortcut. Add actions, then `write()` and `sign()`; Shortcuts names the import after the file, which defaults to `<name>.shortcut`. */
 export declare class Shortcut {
     readonly name: string;
     readonly actions: Action[];
     private readonly color;
     private readonly glyph;
     private readonly inputClasses;
+    private readonly types;
     constructor(name: string, options?: ShortcutOptions);
     /**
-     * Append an action. With an identifier from `actions`, parameter keys are checked at compile
-     * time; any identifier is also validated at run time against the bundled definitions.
+     * Append an action and return it; `ref()` it to use its output. Catalog identifiers are checked:
+     * wrong keys and values don't compile, and unknown keys or unreadable references throw. Other
+     * identifiers pass through unchecked.
      */
     action<I extends string>(identifier: I, params?: ParamsFor<I>): Action;
+    /** Open an If block on `subject`. `condition` is a `CONDITION` name or code; `value` is what it compares with, if anything. Returns the id for `otherwise()` and `endIf()`. */
     if(subject: Attachment, condition: Condition | number, value?: string | number): string;
+    /** Start the Otherwise branch of If block `gid`. */
     otherwise(gid: string): void;
+    /** Close If block `gid`. */
     endIf(gid: string): void;
-    repeatEach(items: Attachment): string;
-    endRepeatEach(gid: string): void;
-    /** Open a Repeat block that runs `count` times; returns the grouping identifier for endRepeatCount(). */
-    repeatCount(count: number | Attachment): string;
-    endRepeatCount(gid: string): void;
+    /** Open a Repeat with Each block over `items`; returns the id for `endRepeatEach()`. Inside, use `repeatItem()` and `repeatIndex()`. */
+    repeatEach(items: ParamTypes["is.workflow.actions.repeat.each"]["WFInput"]): string;
+    /** Close a Repeat with Each block and return it; `ref()` it for the Repeat Results. */
+    endRepeatEach(gid: string): Action;
+    /** Open a Repeat block that runs `count` times; returns the id for `endRepeatCount()`. */
+    repeatCount(count: ParamTypes["is.workflow.actions.repeat.count"]["WFRepeatCount"]): string;
+    /** Close a Repeat block and return it; `ref()` it for the Repeat Results. */
+    endRepeatCount(gid: string): Action;
     /**
-     * Open a Choose from Menu block. Follow with one menuItem() per title, in order, each with the
-     * actions of that branch, then endMenu(). Returns the grouping identifier.
+     * Open a Choose from Menu block; returns the id for `menuItem()` and `endMenu()`. Follow with one
+     * `menuItem()` per title, in order, each followed by that branch's actions.
      */
     chooseFromMenu(prompt: string | TokenString, items: string[]): string;
+    /** Start the branch for `title` in menu `gid`. */
     menuItem(gid: string, title: string): void;
+    /** Close menu `gid`. */
     endMenu(gid: string): void;
+    /** The shortcut as a plist object. */
     toPlist(): Record<string, PlistValue>;
+    /** The shortcut as an XML plist. */
     toXml(): string;
-    /** Write the unsigned file. Shortcuts names an import after the file, so the default is "<name>.shortcut". Converts to binary plist via plutil when present. */
+    /** Write the unsigned file, `<name>.shortcut` by default, and return its path. Binary if `plutil` is installed, XML otherwise. */
     write(path?: string): Promise<string>;
-    /** Sign with the macOS `shortcuts` command so Shortcuts will import the file. */
+    /** Sign `input` into `output`, which Shortcuts will import, and return `output`. Needs a Mac with an iCloud login. */
     static sign(input: string, output: string, mode?: "anyone" | "people-who-know-me"): string;
 }