osa-bridge/dist/index.d.ts

Cross-platform Apple Events bridge for Node & Electron applications

/** 4-char Apple-event code helpers */
export type AECode = string;
/** Object specifier structure for Apple Events */
export interface AEObjectSpecifier {
    type: "objectSpecifier";
    class: string;
    keyForm: string;
    keyData: string;
    keyDataRaw?: string;
    container?: AEObjectSpecifier;
    humanReadable?: string;
}
/** Common Apple Event parameter types */
export type AEParam = string | number | boolean | null | AEObjectSpecifier | AEParam[] | {
    [key: string]: AEParam;
};
/** Incoming Apple-event payload */
export interface AEEvent {
    suite: AECode;
    event: AECode;
    params: Record<AECode, AEParam>;
    targetApp?: string;
    sourceApp?: string;
    transactionID?: number;
}
/** Return value – anything JS-serialisable turns into an AEDesc */
export type AEResult = string | number | boolean | null;
/** Handler signature */
export type AEHandler = (evt: AEEvent) => Promise<AEResult> | AEResult;
/** Register a handler for (suite,event). Wild-cards allowed. */
export declare function on(suite: AECode, event: AECode, handler: AEHandler): void;
/** Check if Apple Events are supported on this platform */
export declare function isAppleEventsSupported(): boolean;
/** Get current platform information */
export declare function getPlatformInfo(): {
    platform: string;
    supported: boolean;
    error?: string;
    architecture: string;
    nodeVersion: string;
};
/** Get all registered handlers (useful for debugging) */
export declare function getRegisteredHandlers(): string[];
/** Remove a handler */
export declare function off(suite: AECode, event: AECode): boolean;
/** Remove all handlers */
export declare function removeAllHandlers(): void;
/**
 * Helper function to get a human-readable representation of an Apple Event
 * Useful for debugging and logging
 */
export declare function formatAEEvent(evt: AEEvent): string;
/**
 * Helper function to extract commonly used parameter types
 * from Apple Event parameters
 */
export declare function extractCommonParams(params: Record<AECode, AEParam>): {
    directObject: AEParam;
    subject: AEParam;
    result: AEParam;
    data: AEParam;
    text: AEParam;
    file: AEParam;
    url: AEParam;
};
/**
 * Type guard to check if a parameter is an object specifier
 */
export declare function isObjectSpecifier(param: AEParam): param is AEObjectSpecifier;
/**
 * Extract the human-readable representation from an object specifier
 * Falls back to building it from the components if not available
 */
export declare function getObjectSpecifierDescription(param: AEParam): string;
/**
 * Extract all object specifiers from event parameters recursively
 */
export declare function extractObjectSpecifiers(params: Record<AECode, AEParam>): AEObjectSpecifier[];