shortcutkit 0.6.1 → 0.8.1

package/dist/index.d.ts

@@ -1,18 +1,47 @@
 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";
 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>;
 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. */
+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. */
+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, subject, plainString, plainNumber, dictionary, quantity, filter, any. */
+    kinds: Record<string, string>;
+    /** Output name, or null when the action produces nothing. */
+    output: string | null;
+    /** Content types the output can be; empty when the action produces nothing. */
+    outputTypes: readonly string[];
+    /** Present for App Intents actions; written as the AppIntentDescriptor parameter. */
+    descriptor?: AppIntentDescriptor;
+    /** The engine's definition, for built-ins only. */
+    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.
+ */
+export declare function getAction(identifier: string): CatalogEntry | undefined;
 /** Names the app that provides an App Intents action; written as the AppIntentDescriptor parameter. */
 export type AppIntentDescriptor = {
     BundleIdentifier: string;
@@ -58,20 +87,35 @@ 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;
+export declare const ref: (action: Action, outputName?: string) => Attachment<"ActionOutput">;
+export declare const variable: (name: string) => Attachment<"Variable">;
+export declare const shortcutInput: () => Attachment<"ExtensionInput">;
+export declare const clipboard: () => Attachment<"Clipboard">;
+export declare const currentDate: () => Attachment<"CurrentDate">;
+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">;
+/** Wrap an attachment as the subject of an If condition, the form the app writes for `WFInput` on `is.workflow.actions.conditional`. Variable-picker parameters (Repeat with Each, Filter, Quick Look, …) take the bare attachment instead. */
+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">;
 /** A WFTextTokenString: strings and attachments interleaved; each attachment becomes U+FFFC. */
 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 {
     color?: IconColor | number;
     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[];
 }
 export declare class Shortcut {
     readonly name: string;
@@ -79,20 +123,23 @@ export declare class Shortcut {
     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.
      */
     action<I extends string>(identifier: I, params?: ParamsFor<I>): Action;
-    if(subject: Attachment, condition: Condition | number, value?: string | number): string;
+    if(subject_: Attachment, condition: Condition | number, value?: string | number): string;
     otherwise(gid: string): void;
     endIf(gid: string): void;
-    repeatEach(items: Attachment): string;
-    endRepeatEach(gid: string): void;
+    repeatEach(items: ParamTypes["is.workflow.actions.repeat.each"]["WFInput"]): string;
+    /** Close a Repeat with Each block. The returned action is the block's output: `ref()` it for the collected "Repeat Results". */
+    endRepeatEach(gid: string): Action;
     /** Open a Repeat block that runs `count` times; returns the grouping identifier for endRepeatCount(). */
-    repeatCount(count: number | Attachment): string;
-    endRepeatCount(gid: string): void;
+    repeatCount(count: ParamTypes["is.workflow.actions.repeat.count"]["WFRepeatCount"]): string;
+    /** Close a Repeat block. The returned action is the block's output: `ref()` it for the collected "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.