applescript-node 1.0.1

package/dist/builder.d.ts

@@ -0,0 +1,725 @@
+import { ExprBuilder } from './expressions.js';
+import type { AppleScriptValue, JsonObjectShape, ScriptBuilder } from './types.js';
+export declare class AppleScriptBuilder implements ScriptBuilder {
+    private script;
+    private indentLevel;
+    private readonly INDENT;
+    private blockStack;
+    private getIndentation;
+    private escapeString;
+    private formatValue;
+    private makeRecord;
+    private validateBlockStack;
+    private pushBlock;
+    private popBlock;
+    private validateBlockType;
+    private addLine;
+    tell(target: string): this;
+    tellTarget(target: string): this;
+    tellProcess(processName: string): this;
+    on(handlerName: string, parameters?: string[]): this;
+    /**
+     * Define a handler using the 'to' syntax (alternative to 'on').
+     * Both 'on' and 'to' are equivalent in AppleScript.
+     * @param handlerName The name of the handler
+     * @param parameters Optional array of parameter names
+     * @returns This builder instance for method chaining
+     * @example
+     * .to('sayHello', ['name'])
+     *   .displayDialog('Hello ' & name)
+     * .endto()
+     */
+    to(handlerName: string, parameters?: string[]): this;
+    /**
+     * Call/invoke a handler with parameters.
+     * @param handlerName The name of the handler to call
+     * @param parameters Optional array of parameter values
+     * @returns This builder instance for method chaining
+     * @example
+     * .callHandler('sayHello', ['"John"'])
+     * .callHandler('processFile', ['theFile', 'true'])
+     */
+    callHandler(handlerName: string, parameters?: string[]): this;
+    /**
+     * Call a handler from within a tell statement using 'my' keyword.
+     * Required when calling handlers from within tell blocks.
+     * @param handlerName The name of the handler to call
+     * @param parameters Optional array of parameter values
+     * @returns This builder instance for method chaining
+     * @example
+     * .tell('Finder')
+     *   .my('processFile', ['theFile'])
+     * .endtell()
+     */
+    my(handlerName: string, parameters?: string[]): this;
+    /**
+     * Call a handler from within a tell statement using 'of me' syntax.
+     * Alternative to 'my' keyword for calling handlers from within tell blocks.
+     * @param handlerName The name of the handler to call
+     * @param parameters Optional array of parameter values
+     * @returns This builder instance for method chaining
+     * @example
+     * .tell('Finder')
+     *   .ofMe('processFile', ['theFile'])
+     * .endtell()
+     */
+    ofMe(handlerName: string, parameters?: string[]): this;
+    /**
+     * Define a handler with labeled parameters (interleaved syntax).
+     * AppleScript supports splitting parameter names with colons and spaces.
+     * @param handlerName The name of the handler
+     * @param labeledParams Object with parameter labels and values
+     * @returns This builder instance for method chaining
+     * @example
+     * .onLabeled('displayError', { message: 'theErrorMessage', buttons: 'theButtons' })
+     *   .displayDialog(theErrorMessage, { buttons: theButtons })
+     * .endon()
+     */
+    onLabeled(handlerName: string, labeledParams: Record<string, string>): this;
+    /**
+     * Define a handler with labeled parameters using 'to' syntax.
+     * @param handlerName The name of the handler
+     * @param labeledParams Object with parameter labels and values
+     * @returns This builder instance for method chaining
+     */
+    toLabeled(handlerName: string, labeledParams: Record<string, string>): this;
+    /**
+     * Define a 'run' event handler (implicit or explicit).
+     * The run handler is called when a script executes.
+     * @param explicit If true, explicitly define the run handler; if false, use implicit
+     * @returns This builder instance for method chaining
+     * @example
+     * .runHandler(true)  // Explicit: on run ... end run
+     *   .displayDialog('Script is running')
+     * .endrun()
+     */
+    runHandler(explicit?: boolean): this;
+    /**
+     * Define a 'quit' event handler.
+     * Called when a script app quits.
+     * @returns This builder instance for method chaining
+     * @example
+     * .quitHandler()
+     *   .displayDialog('Script is quitting')
+     * .endquit()
+     */
+    quitHandler(): this;
+    /**
+     * Define an 'open' event handler for drag-and-drop support.
+     * Makes the script app drag-and-droppable.
+     * @param parameterName Name for the dropped items parameter (default: 'theDroppedItems')
+     * @returns This builder instance for method chaining
+     * @example
+     * .openHandler('theFiles')
+     *   .repeatWith('aFile', 'theFiles')
+     *     .displayDialog('Processing: ' & aFile)
+     *   .endrepeat()
+     * .endopen()
+     */
+    openHandler(parameterName?: string): this;
+    /**
+     * Define an 'idle' event handler for stay-open applications.
+     * Called periodically in stay-open script apps.
+     * @param returnSeconds Number of seconds to wait before next idle call (default: 30)
+     * @returns This builder instance for method chaining
+     * @example
+     * .idleHandler(5)  // Check every 5 seconds
+     *   .displayDialog('Idle processing')
+     *   .return(5)  // Return 5 seconds for next idle
+     * .endidle()
+     */
+    idleHandler(_returnSeconds?: number): this;
+    end(): this;
+    /**
+     * Explicitly end an if block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endif(): this;
+    /**
+     * Explicitly end a repeat block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endrepeat(): this;
+    /**
+     * Explicitly end a try block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endtry(): this;
+    /**
+     * Explicitly end a tell block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endtell(): this;
+    /**
+     * Explicitly end an on handler block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endon(): this;
+    /**
+     * Explicitly end a considering block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endconsidering(): this;
+    /**
+     * Explicitly end an ignoring block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endignoring(): this;
+    /**
+     * Explicitly end a using block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endusing(): this;
+    /**
+     * Explicitly end a with block.
+     * Preferred over end() for clarity when working with multiple nested blocks.
+     */
+    endwith(): this;
+    /**
+     * Explicitly end a 'to' handler block.
+     * Preferred over end() for clarity when working with handlers.
+     */
+    endto(): this;
+    /**
+     * Explicitly end a 'run' handler block.
+     * Preferred over end() for clarity when working with run handlers.
+     */
+    endrun(): this;
+    /**
+     * Explicitly end a 'quit' handler block.
+     * Preferred over end() for clarity when working with quit handlers.
+     */
+    endquit(): this;
+    /**
+     * Explicitly end an 'open' handler block.
+     * Preferred over end() for clarity when working with open handlers.
+     */
+    endopen(): this;
+    /**
+     * Explicitly end an 'idle' handler block.
+     * Preferred over end() for clarity when working with idle handlers.
+     */
+    endidle(): this;
+    if(condition: string | ((expr: ExprBuilder) => string)): this;
+    thenBlock(): this;
+    else(): this;
+    elseIf(condition: string): this;
+    repeat(times?: number): this;
+    repeatWith(variable: string, list: string): this;
+    repeatUntil(condition: string): this;
+    repeatWhile(condition: string): this;
+    repeatWithRange(variable: string, start: number | string, end: number | string): this;
+    exitRepeat(): this;
+    exitRepeatIf(condition: string | ((expr: ExprBuilder) => string)): this;
+    continueRepeat(): this;
+    considering(attributes: string[]): this;
+    ignoring(attributes: string[]): this;
+    using(terms: string[]): this;
+    with(timeout?: number, transaction?: boolean): this;
+    try(): this;
+    onError(variableName?: string): this;
+    error(message: string, number?: number): this;
+    return(value: AppleScriptValue): this;
+    returnRaw(expression: string): this;
+    /**
+     * Build a JSON object string from AppleScript variables.
+     * Generates clean, readable JSON without manual string concatenation.
+     *
+     * @param variableMap Mapping of JSON keys to AppleScript variable names
+     * @returns AppleScript expression that evaluates to a JSON string
+     *
+     * @example
+     * // Instead of manual string building:
+     * // '"{" & "\\"name\\":\\"" & winName & "\\"}" '
+     *
+     * // Use:
+     * const jsonExpr = builder.buildJsonObject({
+     *   name: 'winName',
+     *   position: 'winPosition',
+     *   size: 'winSize'
+     * });
+     * builder.returnRaw(jsonExpr);
+     *
+     * // Generates: '{"name":"Calculator","position":"100,200","size":"800x600"}'
+     */
+    buildJsonObject(variableMap: Record<string, string>): string;
+    /**
+     * Build and return a JSON object from AppleScript variables.
+     * Convenience method that combines buildJsonObject() with returnRaw().
+     *
+     * @param variableMap Mapping of JSON keys to AppleScript variable names
+     *
+     * @example
+     * .setExpression('winName', 'name of window 1')
+     * .setExpression('winPosition', 'position of window 1 as text')
+     * .returnJsonObject({
+     *   name: 'winName',
+     *   position: 'winPosition'
+     * })
+     */
+    returnJsonObject<TProperties extends Record<string, string>>(variableMap: TProperties): ScriptBuilder<never, JsonObjectShape<TProperties>>;
+    /**
+     * Ultra-convenient shorthand for the common "map collection to JSON" pattern.
+     * Replaces verbose manual iteration, property extraction, and JSON conversion.
+     *
+     * This single method handles:
+     * - Creating temporary collection list
+     * - Iterating through items (with optional limit/condition)
+     * - Extracting properties with smart detection (simple vs complex expressions)
+     * - Field-level transformations (firstOf, ifExists, type conversion)
+     * - Error handling (skip failed items)
+     * - JSON serialization and return
+     *
+     * @param itemVariable Loop variable name (e.g., 'aNote')
+     * @param collection Collection to iterate (e.g., 'every note')
+     * @param properties Mapping of JSON keys to AppleScript properties or PropertyExtractor objects
+     * @param options Optional: limit, until/while conditions, error handling
+     *
+     * @example
+     * // Simple properties
+     * .tell('Notes')
+     * .mapToJson('aNote', 'every note', {
+     *   id: 'id',
+     *   name: 'name',
+     *   content: 'plaintext',
+     *   created: 'creation date of aNote as string',
+     * }, { limit: 10, skipErrors: true })
+     * .endtell()
+     *
+     * @example
+     * // Advanced field extractors (NEW!)
+     * .tell('Contacts')
+     * .mapToJson('aPerson', 'every person', {
+     *   id: 'id',
+     *   name: 'name',
+     *   email: { property: (e) => e.property('aPerson', 'emails'), firstOf: true },
+     *   phone: { property: 'phones', firstOf: true },
+     *   birthday: { property: 'birth date', ifExists: true, asType: 'string' },
+     * }, { limit: 50, skipErrors: true })
+     * .endtell()
+     */
+    mapToJson<TProperties extends Record<string, string | {
+        readonly property?: string | ((e: ExprBuilder) => string);
+        readonly firstOf?: boolean;
+        readonly ifExists?: boolean;
+        readonly asType?: string;
+        readonly default?: string | ((e: ExprBuilder) => string);
+    }>>(itemVariable: string, collection: string, properties: TProperties, options?: {
+        limit?: number;
+        until?: string | ((expr: ExprBuilder) => string);
+        while?: string | ((expr: ExprBuilder) => string);
+        skipErrors?: boolean;
+    }): ScriptBuilder<never, JsonObjectShape<TProperties>[]>;
+    /**
+     * Return a list of records as a JSON string.
+     * Converts AppleScript records to JSON format by manually building the JSON string.
+     * Handles proper escaping of strings, booleans, numbers, and null values.
+     * @param listVariable Name of the variable containing a list of records
+     * @param propertyMap Mapping of JSON keys to AppleScript property names (e.g., {id: 'noteId', name: 'noteName'})
+     */
+    returnAsJson<TProperties extends Record<string, string>>(listVariable: string, propertyMap: TProperties): ScriptBuilder<never, JsonObjectShape<TProperties>[]>;
+    log(message: string): this;
+    comment(text: string): this;
+    activate(): this;
+    quit(): this;
+    reopen(): this;
+    launch(): this;
+    running(): this;
+    closeWindow(window?: string): this;
+    closeAllWindows(): this;
+    minimizeWindow(window?: string): this;
+    zoomWindow(window?: string): this;
+    click(target: string): this;
+    select(target: string): this;
+    keystroke(text: string, modifiers?: string[]): this;
+    /**
+     * Type multiple characters with automatic delays between each keystroke.
+     * Convenient shorthand for typing sequences like numbers or text.
+     * @param text String of characters to type (each character gets a separate keystroke)
+     * @param delayBetween Delay in seconds between each keystroke (default: 0.1)
+     * @example
+     * // Instead of:
+     * // .keystroke('1').delay(0.1).keystroke('2').delay(0.1).keystroke('3')
+     * // Use:
+     * // .keystrokes('123')
+     */
+    keystrokes(text: string, delayBetween?: number): this;
+    delay(seconds: number): this;
+    displayDialog(text: string, options?: {
+        buttons?: string[];
+        defaultButton?: string;
+        withIcon?: 'stop' | 'note' | 'caution';
+        givingUpAfter?: number;
+    }): ScriptBuilder;
+    displayNotification(text: string, options?: {
+        title?: string;
+        subtitle?: string;
+        sound?: string;
+    }): ScriptBuilder;
+    set<TNewVar extends string>(variable: TNewVar, value: AppleScriptValue): ScriptBuilder<TNewVar>;
+    setExpression<TNewVar extends string>(variable: TNewVar, expression: string | Record<string, string> | ((expr: ExprBuilder) => string)): ScriptBuilder<TNewVar>;
+    setExpressions(expressions: Record<string, string | ((expr: ExprBuilder) => string)>): this;
+    appendTo(variable: string, expression: string | ((expr: ExprBuilder) => string), options?: {
+        prependLinefeed?: boolean;
+        appendLinefeed?: boolean;
+    }): this;
+    increment(variable: string, by?: number): this;
+    decrement(variable: string, by?: number): this;
+    get(property: string): this;
+    copy<TNewVar extends string>(value: AppleScriptValue, to: TNewVar): ScriptBuilder<TNewVar>;
+    count(items: string): this;
+    setCountOf<TNewVar extends string>(variable: TNewVar, items: string): ScriptBuilder<TNewVar>;
+    exists(item: string): this;
+    setEnd(variable: string, value: AppleScriptValue): this;
+    setEndRaw(variable: string, expression: string | Record<string, string> | ((expr: ExprBuilder) => string)): this;
+    setEndRecord(listVariable: string, sourceOrExpressions: string | Record<string, string>, propertyMap?: Record<string, string>): this;
+    /**
+     * Intuitive shorthand for picking properties from a source object and building a record.
+     * Automatically detects full expressions vs simple property names:
+     * - Simple properties (no special keywords) get "of source" appended
+     * - Complex expressions (with 'of', 'as', 'where', etc.) are used as-is
+     *
+     * @param listVariable Name of the list to append the record to
+     * @param sourceObject Name of the source object to extract properties from
+     * @param propertyMap Mapping of record keys to property names/expressions
+     *
+     * @example
+     * // Mix simple properties and complex expressions
+     * .pickEndRecord('notesList', 'aNote', {
+     *   noteId: 'id',                              // => id of aNote
+     *   noteName: 'name',                          // => name of aNote
+     *   noteCreated: 'creation date of aNote as string',  // used as-is (has 'as')
+     *   noteModified: 'modification date as string',      // used as-is (has 'as')
+     * })
+     */
+    pickEndRecord(listVariable: string, sourceObject: string, propertyMap: Record<string, string>): this;
+    /**
+     * Set variable using ternary operator pattern with if-then-else block.
+     * Much more concise than manually calling ifThenElse for simple conditional assignments.
+     *
+     * Generates an if-then-else block that sets the variable conditionally.
+     *
+     * @param variable - Variable name to set
+     * @param condition - Condition to evaluate (string or ExprBuilder callback)
+     * @param trueExpression - Expression to use if condition is true
+     * @param falseExpression - Expression to use if condition is false
+     *
+     * @example
+     * // With ExprBuilder for type-safe conditions
+     * .setTernary('personEmail',
+     *   (e) => e.gt(e.count(e.property('aPerson', 'emails')), 0),
+     *   (e) => e.valueOfItem(1, e.property('aPerson', 'emails')),
+     *   'missing value'
+     * )
+     *
+     * @example
+     * // With strings
+     * .setTernary('status',
+     *   'count of items > 0',
+     *   '"active"',
+     *   '"empty"'
+     * )
+     *
+     * @example
+     * // Replaces verbose ifThenElse:
+     * // .ifThenElse(
+     * //   (e) => e.gt('x', 10),
+     * //   (then_) => then_.set('result', 'high'),
+     * //   (else_) => else_.set('result', 'low')
+     * // )
+     * // With concise ternary:
+     * .setTernary('result', (e) => e.gt('x', 10), '"high"', '"low"')
+     */
+    setTernary<TNewVar extends string>(variable: TNewVar, condition: string | ((e: ExprBuilder) => string), trueExpression: string | ((e: ExprBuilder) => string), falseExpression: string | ((e: ExprBuilder) => string)): ScriptBuilder<TNewVar>;
+    /**
+     * Append to list using ternary operator pattern with if-then-else block.
+     * Combines setEndRaw with conditional logic for ultra-concise syntax.
+     *
+     * Generates an if-then-else block that conditionally appends to the list.
+     *
+     * @param listVariable - Name of the list to append to
+     * @param condition - Condition to evaluate (string or ExprBuilder callback)
+     * @param trueExpression - Expression to append if condition is true
+     * @param falseExpression - Expression to append if condition is false
+     *
+     * @example
+     * // Conditionally append different values
+     * .set('results', [])
+     * .forEach('item', 'every file of desktop', (loop) =>
+     *   loop.setEndTernary('results',
+     *     (e) => e.gt(e.property('item', 'size'), 1000000),
+     *     '"large"',
+     *     '"small"'
+     *   )
+     * )
+     *
+     * @example
+     * // With complex expressions
+     * .setEndTernary('emails',
+     *   'count of email addresses of person > 0',
+     *   'value of item 1 of email addresses of person',
+     *   'missing value'
+     * )
+     */
+    setEndTernary(listVariable: string, condition: string | ((e: ExprBuilder) => string), trueExpression: string | ((e: ExprBuilder) => string), falseExpression: string | ((e: ExprBuilder) => string)): ScriptBuilder;
+    /**
+     * Set variable to first item of collection or default value if collection is empty.
+     * Ultra-shorthand for the common "first or default" pattern.
+     *
+     * Automatically generates an if-then-else block that checks the collection count and sets the variable accordingly.
+     *
+     * @template TNewVar - The variable name (inferred from first parameter)
+     * @param variable - Variable name to set (will be added to scope)
+     * @param collection - Collection expression to get first item from
+     * @param defaultValue - Value to use if collection is empty (default: 'missing value')
+     *
+     * @example
+     * // Get first email or missing value
+     * .setFirstOf('personEmail', (e) => e.property('aPerson', 'emails'))
+     *
+     * @example
+     * // Get first email or custom default
+     * .setFirstOf('personEmail', (e) => e.property('aPerson', 'emails'), '"no-email@example.com"')
+     *
+     * @example
+     * // With string expression
+     * .setFirstOf('personEmail', 'emails of aPerson', 'missing value')
+     *
+     * @example
+     * // Replaces verbose pattern:
+     * // .setTernary('personEmail',
+     * //   (e) => e.gt(e.count(e.property('aPerson', 'emails')), 0),
+     * //   (e) => e.valueOfItem(1, e.property('aPerson', 'emails')),
+     * //   'missing value'
+     * // )
+     */
+    setFirstOf<TNewVar extends string>(variable: TNewVar, collection: string | ((e: ExprBuilder) => string), defaultValue?: string | ((e: ExprBuilder) => string)): ScriptBuilder<TNewVar>;
+    /**
+     * Append first item of collection or default value to a list.
+     * Ultra-shorthand for the common "first or default" pattern in list building.
+     *
+     * Automatically generates an if-then-else block that checks the collection count and appends to the list accordingly.
+     *
+     * @param listVariable - Name of the list to append to
+     * @param collection - Collection expression to get first item from
+     * @param defaultValue - Value to use if collection is empty (default: 'missing value')
+     *
+     * @example
+     * // Build list of first emails
+     * .forEach('person', 'every person', (loop) =>
+     *   loop.setEndFirstOf('emails', (e) => e.property('person', 'email addresses'))
+     * )
+     *
+     * @example
+     * // With custom default
+     * .setEndFirstOf('results', 'items of record', '""')
+     */
+    setEndFirstOf(listVariable: string, collection: string | ((e: ExprBuilder) => string), defaultValue?: string | ((e: ExprBuilder) => string)): ScriptBuilder;
+    /**
+     * Set variable to property value if it exists, otherwise use default value.
+     * Ultra-shorthand for the common "take if exists or default" pattern.
+     *
+     * Automatically generates an if-then-else block that checks if the property exists
+     * and sets the variable accordingly, with optional type conversion.
+     *
+     * @template TNewVar - The variable name (inferred from first parameter)
+     * @param variable - Variable name to set (will be added to scope)
+     * @param property - Property expression to check and retrieve
+     * @param defaultValue - Value to use if property doesn't exist (default: 'missing value')
+     * @param asType - Optional type to convert property to (e.g., 'string', 'integer')
+     *
+     * @example
+     * // Get birth date as string or missing value
+     * .setIfExists('personBirthday',
+     *   (e) => e.property('aPerson', 'birth date'),
+     *   'missing value',
+     *   'string'
+     * )
+     *
+     * @example
+     * // Simpler syntax with string expression
+     * .setIfExists('personBirthday', 'birth date of aPerson', 'missing value', 'string')
+     *
+     * @example
+     * // Without type conversion
+     * .setIfExists('personNote', 'note of aPerson', '""')
+     *
+     * @example
+     * // Replaces verbose pattern:
+     * // .setTernary('personBirthday',
+     * //   (e) => e.exists(e.property('aPerson', 'birth date')),
+     * //   (e) => e.asType(e.property('aPerson', 'birth date'), 'string'),
+     * //   'missing value'
+     * // )
+     */
+    setIfExists<TNewVar extends string>(variable: TNewVar, property: string | ((e: ExprBuilder) => string), defaultValue?: string | ((e: ExprBuilder) => string), asType?: string): ScriptBuilder<TNewVar>;
+    /**
+     * Append property value to list if it exists, otherwise append default value.
+     * Ultra-shorthand for the common "take if exists or default" pattern in list building.
+     *
+     * Automatically generates an if-then-else block that checks if the property exists
+     * and appends to the list accordingly, with optional type conversion.
+     *
+     * @param listVariable - Name of the list to append to
+     * @param property - Property expression to check and retrieve
+     * @param defaultValue - Value to use if property doesn't exist (default: 'missing value')
+     * @param asType - Optional type to convert property to (e.g., 'string', 'integer')
+     *
+     * @example
+     * // Build list of birth dates
+     * .forEach('person', 'every person', (loop) =>
+     *   loop.setEndIfExists('dates', 'birth date of person', '""', 'string')
+     * )
+     *
+     * @example
+     * // With ExprBuilder
+     * .setEndIfExists('notes',
+     *   (e) => e.property('contact', 'note'),
+     *   'missing value'
+     * )
+     */
+    setEndIfExists(listVariable: string, property: string | ((e: ExprBuilder) => string), defaultValue?: string | ((e: ExprBuilder) => string), asType?: string): ScriptBuilder;
+    setProperty(variable: string, property: string, value: AppleScriptValue): this;
+    makeRecordFrom(variableNames: Record<string, string>): string;
+    first(items: string): this;
+    last(items: string): this;
+    rest(items: string): this;
+    reverse(items: string): this;
+    some(items: string, test: string): this;
+    every(items: string, test: string): this;
+    whose(items: string, condition: string): string;
+    getEvery(itemType: string, location?: string): this;
+    getEveryWhere(itemType: string, condition: string, location?: string): this;
+    offset(text: string, in_: string): this;
+    contains(text: string, in_: string): this;
+    beginsWith(text: string, with_: string): this;
+    endsWith(text: string, with_: string): this;
+    path(to: string): this;
+    info(for_: string): this;
+    do(script: string): this;
+    doShellScript(command: string, administrator?: boolean): this;
+    raw(script: string): this;
+    getRunningApplications(): this;
+    getFrontmostApplication(): this;
+    activateApplication(appName: string): this;
+    hideApplication(appName: string): this;
+    unhideApplication(appName: string): this;
+    quitApplication(appName: string): this;
+    isApplicationRunning(appName: string): this;
+    getApplicationInfo(appName: string): this;
+    getWindowInfo(appName: string, windowName?: string): this;
+    getAllWindows(appName: string): this;
+    getFrontmostWindow(appName: string): this;
+    setWindowBounds(appName: string, windowName: string, bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): this;
+    moveWindow(appName: string, windowName: string, x: number, y: number): this;
+    resizeWindow(appName: string, windowName: string, width: number, height: number): this;
+    arrangeWindows(arrangement: 'cascade' | 'tile' | 'stack'): this;
+    focusWindow(appName: string, windowName: string): this;
+    switchToWindow(appName: string, windowName: string): this;
+    pressKey(key: string, modifiers?: ('command' | 'option' | 'control' | 'shift')[]): this;
+    pressKeyCode(keyCode: number, modifiers?: ('command' | 'option' | 'control' | 'shift')[]): this;
+    typeText(text: string): this;
+    clickButton(buttonName: string): this;
+    clickMenuItem(menuName: string, itemName: string): this;
+    /**
+     * Simplified tell application pattern with automatic block closing.
+     * Cleaner than manually calling tell()...end().
+     * @param appName Name of the application to tell
+     * @param block Callback that builds commands for the application
+     */
+    tellApp(appName: string, block: (builder: ScriptBuilder) => void): this;
+    /**
+     * Simplified if-then pattern that automatically closes the if block.
+     * Cleaner than manually calling if()...thenBlock()...endif().
+     * @param condition The condition to check (string or ExprBuilder callback)
+     * @param thenBlock Callback that builds the then branch
+     */
+    ifThen(condition: string | ((expr: ExprBuilder) => string), thenBlock: (builder: ScriptBuilder) => void): this;
+    /**
+     * Simplified if-then-else pattern that automatically closes the if block.
+     * Cleaner than manually calling if()...thenBlock()...else()...endif().
+     * @param condition The condition to check (string or ExprBuilder callback)
+     * @param thenBlock Callback that builds the then branch
+     * @param elseBlock Callback that builds the else branch
+     */
+    ifThenElse(condition: string | ((expr: ExprBuilder) => string), thenBlock: (builder: ScriptBuilder) => void, elseBlock: (builder: ScriptBuilder) => void): this;
+    /**
+     * Simplified try-catch pattern that automatically closes the try block.
+     * Cleaner than manually calling try()...onError()...endtry().
+     * @param tryBlock Callback that builds the try branch
+     * @param catchBlock Callback that builds the on error branch
+     */
+    tryCatch(tryBlock: (builder: ScriptBuilder) => void, catchBlock: (builder: ScriptBuilder) => void): this;
+    /**
+     * Simplified try-catch pattern with error variable capture.
+     * @param tryBlock Callback that builds the try branch
+     * @param errorVarName Name of the variable to capture the error
+     * @param catchBlock Callback that builds the on error branch
+     */
+    tryCatchError(tryBlock: (builder: ScriptBuilder) => void, errorVarName: string, catchBlock: (builder: ScriptBuilder) => void): this;
+    /**
+     * Iterate over items with automatic block closing.
+     * More intuitive name for repeatWith that uses callback pattern.
+     * @param variable Loop variable name
+     * @param list Expression for the list to iterate (e.g., 'every note')
+     * @param block Callback that builds the loop body
+     */
+    forEach<TNewVar extends string>(variable: TNewVar, list: string, block: (builder: ScriptBuilder<TNewVar>) => void): this;
+    /**
+     * Iterate over items while a condition is true.
+     * Combines forEach with an early exit condition for cleaner syntax.
+     * @param variable Loop variable name
+     * @param list Expression for the list to iterate (e.g., 'every note')
+     * @param condition Condition to check before each iteration (continues while true)
+     * @param block Callback that builds the loop body
+     */
+    forEachWhile<TNewVar extends string>(variable: TNewVar, list: string, condition: string | ((expr: ExprBuilder<TNewVar>) => string), block: (builder: ScriptBuilder<TNewVar>) => void): this;
+    /**
+     * Iterate over items until a condition becomes true.
+     * Combines forEach with an early exit condition for cleaner syntax.
+     * @param variable Loop variable name
+     * @param list Expression for the list to iterate (e.g., 'every note')
+     * @param condition Condition to check before each iteration (exits when true)
+     * @param block Callback that builds the loop body
+     */
+    forEachUntil<TNewVar extends string>(variable: TNewVar, list: string, condition: string | ((expr: ExprBuilder<TNewVar>) => string), block: (builder: ScriptBuilder<TNewVar>) => void): this;
+    /**
+     * Repeat a fixed number of times with automatic block closing.
+     * @param times Number of times to repeat
+     * @param block Callback that builds the loop body
+     */
+    repeatTimes(times: number, block: (builder: ScriptBuilder) => void): this;
+    /**
+     * Repeat while condition is true with automatic block closing.
+     * @param condition Condition to check (continues while true)
+     * @param block Callback that builds the loop body
+     */
+    repeatWhileBlock(condition: string, block: (builder: ScriptBuilder) => void): this;
+    /**
+     * Repeat until condition is true with automatic block closing.
+     * @param condition Condition to check (continues until true)
+     * @param block Callback that builds the loop body
+     */
+    repeatUntilBlock(condition: string, block: (builder: ScriptBuilder) => void): this;
+    /**
+     * Load an existing AppleScript into the builder, preserving its structure.
+     * Parses the script to detect block structure (tell, if, repeat, etc.) and
+     * maintains proper nesting so you can continue editing with the builder API.
+     * @param script The AppleScript source code to load
+     * @returns This builder instance for method chaining
+     */
+    loadFromScript(script: string): this;
+    /**
+     * Helper method to extract the target from a tell statement.
+     * @param line The tell statement line
+     * @returns The extracted target or undefined
+     */
+    private extractTarget;
+    build(): string;
+    reset(): this;
+}