Decorators

/**
 * Class decorator that configures plugin metadata
 * @param config - Plugin configuration object
 * @returns ClassDecorator
 */
function Plugin(config: PluginConfig): ClassDecorator;

interface PluginConfig {
  /** Plugin name, should match the class name */
  pluginName: string;
  /** Plugin NPM package name */
  plugin: string;
  /** Plugin object reference path (optional) */
  pluginRef?: string;
  /** GitHub repository URL (optional) */
  repo?: string;
  /** Custom install command (optional) */
  install?: string;
  /** Available installation variables (optional) */
  installVariables?: string[];
  /** Supported platforms (optional) */
  platforms?: string[];
  /** Additional configuration properties */
  [key: string]: any;
}

@Plugin({
  pluginName: "Camera",
  plugin: "cordova-plugin-camera",
  pluginRef: "navigator.camera",
  repo: "https://github.com/apache/cordova-plugin-camera",
  platforms: ["Android", "iOS", "Windows"],
  install: "ionic cordova plugin add cordova-plugin-camera"
})
export class Camera extends IonicNativePlugin {
  // Methods here
}

/**
 * Method decorator for wrapping Cordova plugin methods
 * Automatically handles Promise/Observable conversion and error checking
 * @param config - Optional configuration for the method wrapper
 * @returns MethodDecorator
 */
function Cordova(config?: CordovaOptions): MethodDecorator;

interface CordovaOptions {
  /** Destructure callback arguments into an array */
  destruct?: boolean;
  /** Override the native method name if different from TypeScript method */
  methodName?: string;
  /** Mark the method as synchronous (no Promise wrapping) */
  sync?: boolean;
  /** Callback parameter order - set to "reverse" if success/error are first */
  callbackOrder?: "reverse";
  /** Callback style for different callback patterns */
  callbackStyle?: "node" | "object";
  /** Custom index for success callback */
  successIndex?: number;
  /** Custom index for error callback */
  errorIndex?: number;
  /** Success property name for object-style callbacks */
  successName?: string;
  /** Error property name for object-style callbacks */
  errorName?: string;
  /** Return an Observable instead of Promise */
  observable?: boolean;
  /** Method name to call for clearing/stopping Observable */
  clearFunction?: string;
  /** Call clear function with same arguments as original */
  clearWithArgs?: boolean;
  /** Create Observable from global event instead of plugin method */
  eventObservable?: boolean;
  /** Event name for event-based Observables */
  event?: string;
  /** Element to attach event listener to (defaults to window) */
  element?: any;
  /** Method returns a promise natively */
  otherPromise?: boolean;
  /** Platform restrictions for this method */
  platforms?: string[];
}

export class Camera extends IonicNativePlugin {
  // Basic Promise method
  @Cordova()
  getPicture(options?: CameraOptions): Promise<string> {
    return;
  }
  
  // Observable method
  @Cordova({ observable: true })
  watchHeading(): Observable<CompassHeading> {
    return;
  }
  
  // Synchronous method
  @Cordova({ sync: true })
  getVersion(): string {
    return;
  }
  
  // Custom callback configuration
  @Cordova({
    callbackStyle: "object",
    successName: "onSuccess",
    errorName: "onError"
  })
  customMethod(options: any): Promise<any> {
    return;
  }
}

/**
 * Property decorator for Cordova plugin properties
 * Provides getter/setter access to native plugin properties
 * @returns PropertyDecorator
 */
function CordovaProperty(): PropertyDecorator;

export class StatusBar extends IonicNativePlugin {
  @CordovaProperty()
  isVisible: boolean;
  
  // Usage: StatusBar.isVisible will get/set the native property
}

/**
 * Method decorator for plugin instance methods
 * Similar to @Cordova but operates on plugin object instances
 * @param config - Optional configuration for the instance method wrapper
 * @returns MethodDecorator
 */
function CordovaInstance(config?: CordovaOptions): MethodDecorator;

export class File extends IonicNativePlugin {
  private _objectInstance: any;
  
  @CordovaInstance()
  readAsText(path: string): Promise<string> {
    return;
  }
}

/**
 * Property decorator for plugin instance properties
 * Provides access to properties on the _objectInstance
 * @returns PropertyDecorator
 */
function InstanceProperty(): PropertyDecorator;

export class MediaObject extends IonicNativePlugin {
  private _objectInstance: any;
  
  @InstanceProperty()
  duration: number;
}

/**
 * Method decorator that overrides a native function with an Observable
 * Useful for callback functions that need to be overridden
 * @returns MethodDecorator
 */
function CordovaFunctionOverride(): MethodDecorator;

export class BackgroundMode extends IonicNativePlugin {
  @CordovaFunctionOverride()
  onactivate(): Observable<any> {
    return;
  }
}

/**
 * Method decorator for checking availability before method execution
 * @param config - Optional configuration for availability checking
 * @returns MethodDecorator
 */
function CordovaCheck(config?: CordovaOptions): MethodDecorator;

/**
 * Method decorator for checking instance availability before method execution
 * @param config - Optional configuration for instance availability checking
 * @returns MethodDecorator
 */
function InstanceCheck(config?: CordovaOptions): MethodDecorator;

@Cordova({
  observable: true,
  clearFunction: "clearWatch",
  clearWithArgs: true
})
watchPosition(): Observable<Geoposition> {
  return;
}

@Cordova({
  eventObservable: true,
  event: "deviceready"
})
onDeviceReady(): Observable<any> {
  return;
}

@Cordova({
  platforms: ["iOS"]
})
iOSOnlyMethod(): Promise<any> {
  return;
}

/**
 * Internal function used by @Cordova decorator
 * @param pluginObj - Plugin instance
 * @param methodName - Method name to call
 * @param config - Cordova configuration options
 * @param args - Method arguments
 * @returns Result from plugin method call
 */
function cordova(
  pluginObj: any, 
  methodName: string, 
  config: CordovaOptions, 
  args: IArguments | any[]
): any;

/**
 * Internal function used by @CordovaInstance decorator
 * @param pluginObj - Plugin object with _objectInstance
 * @param methodName - Method name to call on instance
 * @param config - Cordova configuration options
 * @param args - Method arguments
 * @returns Result from instance method call
 */
function cordovaInstance(
  pluginObj: any, 
  methodName: string, 
  config: CordovaOptions, 
  args: IArguments | any[]
): any;

/**
 * Internal function used by @CordovaFunctionOverride decorator
 * @param pluginObj - Plugin instance
 * @param methodName - Method name to override
 * @param args - Method arguments
 * @returns Observable for function override
 */
function cordovaFunctionOverride(
  pluginObj: any, 
  methodName: string, 
  args?: IArguments | any[]
): Observable<any>;

/**
 * Gets property value from Cordova plugin with availability checking
 * @param pluginObj - Plugin instance
 * @param key - Property name
 * @returns Property value or null if plugin/property unavailable
 */
function cordovaPropertyGet(pluginObj: any, key: string): any;

/**
 * Sets property value on Cordova plugin with availability checking
 * @param pluginObj - Plugin instance
 * @param key - Property name
 * @param value - Value to set
 */
function cordovaPropertySet(pluginObj: any, key: string, value: any): void;

/**
 * Gets property value from plugin instance object
 * @param pluginObj - Plugin object with _objectInstance
 * @param key - Property name
 * @returns Property value or null if instance/property unavailable
 */
function instancePropertyGet(pluginObj: any, key: string): any;

/**
 * Sets property value on plugin instance object
 * @param pluginObj - Plugin object with _objectInstance
 * @param key - Property name
 * @param value - Value to set
 */
function instancePropertySet(pluginObj: any, key: string, value: any): void;