Platform Runtime

/**
 * Main Capacitor global interface providing runtime functionality
 */
interface CapacitorGlobal {
  /** Exception class for generating plugin Exceptions from bridge calls */
  Exception: typeof CapacitorException;
  /** Convert file path into usable src for the native WebView */
  convertFileSrc(filePath: string): string;
  /** Get platform name: 'android', 'ios', or 'web' */
  getPlatform(): string;
  /** Check if platform is native (android/ios) */
  isNativePlatform(): boolean;
  /** Check if a plugin is registered and available */
  isPluginAvailable(name: string): boolean;
  /** Register plugin implementations */
  registerPlugin: RegisterPlugin;
  /** Add listener for plugin event (optional on some platforms) */
  addListener?(pluginName: string, eventName: string, callback: PluginCallback): PluginListenerHandle;
  /** Remove listener for plugin event (optional on some platforms) */
  removeListener?(pluginName: string, callbackId: string, eventName: string, callback: PluginCallback): void;
  /** Debug mode flag */
  DEBUG?: boolean;
  /** Logging enabled flag */
  isLoggingEnabled?: boolean;
}

import { Capacitor } from "@capacitor/core";

// Platform detection
const platform = Capacitor.getPlatform();
console.log(`Running on: ${platform}`);

if (Capacitor.isNativePlatform()) {
  // Native-specific code
  console.log('Running on native platform');
}

// File path conversion for WebView
const webViewPath = Capacitor.convertFileSrc('/path/to/file.jpg');

// Plugin availability check
if (Capacitor.isPluginAvailable('Camera')) {
  // Use camera plugin
}

/**
 * Get the name of the platform
 * @returns Platform identifier: 'android', 'ios', or 'web'
 */
getPlatform(): string;

/**
 * Check if the current platform is native
 * @returns true for 'android' and 'ios', false for 'web'
 */
isNativePlatform(): boolean;

import { Capacitor } from "@capacitor/core";

const platform = Capacitor.getPlatform();
switch (platform) {
  case 'android':
    // Android-specific logic
    break;
  case 'ios':
    // iOS-specific logic
    break;
  case 'web':
    // Web-specific logic
    break;
}

// Platform-specific feature checks
if (Capacitor.isNativePlatform()) {
  // Features available on mobile devices
  await enablePushNotifications();
} else {
  // Web-only features or fallbacks
  showWebNotification();
}

/**
 * Register plugin implementations with Capacitor
 * @param pluginName Unique CamelCase name of the plugin
 * @param implementations Map of platform-specific implementations
 * @returns Plugin proxy for method calls
 */
type RegisterPlugin = <T>(
  pluginName: string, 
  implementations?: Readonly<PluginImplementations>
) => T;

/**
 * Map of plugin implementations by platform
 */
type PluginImplementations = {
  [platform: string]: (() => Promise<any>) | any;
};

/**
 * Check if a plugin is registered and available on current platform
 * @param name Plugin name to check
 * @returns true if plugin is available, false otherwise
 */
isPluginAvailable(name: string): boolean;

import { Capacitor, registerPlugin } from "@capacitor/core";

// Define plugin interface
interface EchoPlugin {
  echo(options: { value: string }): Promise<{ value: string }>;
}

// Register plugin with platform implementations
const Echo = registerPlugin<EchoPlugin>('Echo', {
  web: () => import('./echo-web').then(m => new m.EchoWeb()),
  android: () => import('./echo-android').then(m => new m.EchoAndroid()),
});

// Check availability before use
if (Capacitor.isPluginAvailable('Echo')) {
  const result = await Echo.echo({ value: 'Hello World' });
  console.log(result.value);
}

// Register plugin with direct implementations
const MyPlugin = registerPlugin<MyPlugin>('MyPlugin', {
  web: new MyWebImplementation(),
  ios: async () => {
    // Lazy-loaded implementation
    const module = await import('./my-ios-plugin');
    return new module.MyIOSPlugin();
  },
});

/**
 * Convert a file path into a usable src depending on native WebView 
 * implementation and environment
 * @param filePath File path to convert
 * @returns WebView-compatible path
 */
convertFileSrc(filePath: string): string;

import { Capacitor } from "@capacitor/core";

// Convert local file path for WebView usage
const localPath = '/data/user/images/photo.jpg';
const webViewPath = Capacitor.convertFileSrc(localPath);

// Use in HTML img tag
const imgElement = document.createElement('img');
imgElement.src = webViewPath;

// Use in CSS background
const element = document.getElementById('background');
element.style.backgroundImage = `url(${webViewPath})`;

/**
 * Exception class used for plugin and platform errors
 */
class CapacitorException extends Error {
  constructor(
    readonly message: string,
    readonly code?: ExceptionCode,
    readonly data?: ExceptionData,
  );
}

/**
 * Standard exception codes
 */
enum ExceptionCode {
  /** API is not implemented for current platform */
  Unimplemented = 'UNIMPLEMENTED',
  /** API is not available due to missing prerequisites */
  Unavailable = 'UNAVAILABLE',
}

/**
 * Additional exception data
 */
interface ExceptionData {
  [key: string]: any;
}

import { Capacitor, ExceptionCode } from "@capacitor/core";

try {
  await SomePlugin.methodNotAvailableOnWeb();
} catch (error) {
  if (error instanceof Capacitor.Exception) {
    switch (error.code) {
      case ExceptionCode.Unimplemented:
        console.log('Feature not implemented on this platform');
        // Show fallback UI
        break;
      case ExceptionCode.Unavailable:
        console.log('Feature temporarily unavailable');
        // Show retry option
        break;
      default:
        console.error('Plugin error:', error.message);
    }
  }
}

/**
 * Add listener for plugin events (optional, platform-dependent)
 * @param pluginName Name of the plugin
 * @param eventName Name of the event
 * @param callback Function to call when event fires
 * @returns Handle for removing the listener
 */
addListener?(
  pluginName: string, 
  eventName: string, 
  callback: PluginCallback
): PluginListenerHandle;

/**
 * Remove listener for plugin events (optional, platform-dependent)
 * @param pluginName Name of the plugin
 * @param callbackId ID of the callback to remove
 * @param eventName Name of the event
 * @param callback Original callback function
 */
removeListener?(
  pluginName: string, 
  callbackId: string, 
  eventName: string, 
  callback: PluginCallback
): void;

/**
 * Plugin event callback function
 */
type PluginCallback = (data: PluginResultData, error?: PluginResultError) => void;

/**
 * Handle for managing event listeners
 */
interface PluginListenerHandle {
  remove(): Promise<void>;
}