flipper-plugin
Version:
Flipper Desktop plugin SDK and components
200 lines • 9.13 kB
TypeScript
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/
import EventEmitter from 'eventemitter3';
import { SandyPluginDefinition } from './SandyPluginDefinition';
import { MenuEntry, NormalizedMenuEntry } from './MenuEntry';
import { FlipperLib } from './FlipperLib';
import { CrashLogListener, Device, DeviceLogListener } from './DevicePlugin';
import { Idler } from '../utils/Idler';
import { Notification } from './Notification';
import { Logger } from '../utils/Logger';
import { CreatePasteArgs, CreatePasteResult } from './Paste';
import { EventsContract, MethodsContract, ServerAddOnControls } from 'flipper-common';
type StateExportHandler<T = any> = (idler: Idler, onStatusMessage: (msg: string) => void) => Promise<T | undefined | void>;
type StateImportHandler<T = any> = (data: T) => void;
export interface BasePluginClient<ServerAddOnEvents extends EventsContract = {}, ServerAddOnMethods extends MethodsContract = {}> {
/**
* A key that uniquely identifies this plugin instance, captures the current device/client/plugin combination.
*/
readonly pluginKey: string;
readonly device: Device;
/**
* the onDestroy event is fired whenever a device is unloaded from Flipper, or a plugin is disabled.
*/
onDestroy(cb: () => void): void;
/**
* the onActivate event is fired whenever the plugin is actived in the UI
*
* @returns an unsubscribe callback
*/
onActivate(cb: () => void): () => void;
/**
* The counterpart of the `onActivate` handler.
*
* @returns an unsubscribe callback
*/
onDeactivate(cb: () => void): () => void;
/**
* Triggered when this plugin is opened through a deeplink
*
* @returns an unsubscribe callback
*/
onDeepLink(cb: (deepLink: unknown) => void): () => void;
/**
* Triggered when the current plugin is being exported and should create a snapshot of the state exported.
* Overrides the default export behavior and ignores any 'persist' flags of state.
*
* If an object is returned from the handler, that will be taken as export.
* Otherwise, if nothing is returned, the handler will be run, and after the handler has finished the `persist` keys of the different states will be used as export basis.
*/
onExport<T extends object>(exporter: StateExportHandler<T>): void;
/**
* Triggered directly after the plugin instance was created, if the plugin is being restored from a snapshot.
* Should be the inverse of the onExport handler
*/
onImport<T = any>(handler: StateImportHandler<T>): void;
/**
* The `onReady` event is triggered immediately after a plugin has been initialized and any pending state was restored.
* This event fires after `onImport` / the interpretation of any `persist` flags and indicates that the initialization process has finished.
* This event does not signal that the plugin is loaded in the UI yet (see `onActivated`) and does fire before deeplinks (see `onDeepLink`) are handled.
*
* @returns an unsubscribe callback
*/
onReady(handler: () => void): () => void;
/**
* Register menu entries in the Flipper toolbar
*/
addMenuEntry(...entry: MenuEntry[]): void;
/**
* Listener that is triggered if the underlying device emits a log message.
* Listeners established with this mechanism will automatically be cleaned up during destroy
*/
onDeviceLogEntry(cb: DeviceLogListener): () => void;
/**
* Listener that is triggered if the underlying device crashes.
* Listeners established with this mechanism will automatically be cleaned up during destroy
*/
onDeviceCrash(cb: CrashLogListener): () => void;
/**
* Creates a Paste (similar to a Github Gist).
* Facebook only function. Resolves to undefined if creating a paste failed.
*/
createPaste(args: string | CreatePasteArgs): Promise<CreatePasteResult | undefined>;
/**
* Returns true if this is an internal Facebook build.
* Always returns `false` in open source
*/
readonly isFB: boolean;
/**
* Returns true if the user is taking part in the given gatekeeper.
* Always returns `false` in open source.
*/
GK(gkName: string): boolean;
/**
* Shows an urgent, system wide notification, that will also be registered in Flipper's notification pane.
* For on-screen notifications, we recommend to use either the `message` or `notification` API from `antd` directly.
*
* Clicking the notification will open this plugin. If the `action` id is set, it will be used as deeplink.
*/
showNotification(notification: Notification): void;
/**
* Writes text to the clipboard of the Operating System
*/
writeTextToClipboard(text: string): void;
/**
* Logger instance that logs information to the console, but also to the internal logging (in FB only builds) and which can be used to track performance.
*/
logger: Logger;
/**
* Triggered when a server add-on starts.
* You should send messages to the server add-on only after it connects.
* Do not forget to stop all communication when the add-on stops.
* See `onServerAddStop`.
*
* @returns an unsubscribe callback
*/
onServerAddOnStart(callback: () => void): () => void;
/**
* Triggered when a server add-on stops.
* You should stop all communication with the server add-on when the add-on stops.
*
* @returns an unsubscribe callback
*/
onServerAddOnStop(callback: () => void): () => void;
/**
* Subscribe to a specific event arriving from the server add-on.
* Messages can only arrive if the plugin is enabled and connected.
*/
onServerAddOnMessage<Event extends keyof ServerAddOnEvents & string>(event: Event, callback: (params: ServerAddOnEvents[Event]) => void): void;
/**
* Subscribe to all messages arriving from the server add-ons not handled by another listener.
*
* This handler is untyped, and onMessage should be favored over using onUnhandledMessage if the event name is known upfront.
*/
onServerAddOnUnhandledMessage(callback: (event: string, params: any) => void): void;
/**
* Send a message to the server add-on
*/
sendToServerAddOn<Method extends keyof ServerAddOnMethods & string>(method: Method, ...params: Parameters<ServerAddOnMethods[Method]> extends [] ? [] : [Parameters<ServerAddOnMethods[Method]>[0]]): ReturnType<ServerAddOnMethods[Method]>;
}
declare let currentPluginInstance: BasePluginInstance | undefined;
export declare function setCurrentPluginInstance(instance: typeof currentPluginInstance): void;
export declare function getCurrentPluginInstance(): typeof currentPluginInstance;
export interface Persistable {
serialize(): any;
deserialize(value: any): void;
}
export declare function registerStorageAtom(key: string | undefined, persistable: Persistable): void;
export declare abstract class BasePluginInstance {
private readonly serverAddOnControls;
/** generally available Flipper APIs */
readonly flipperLib: FlipperLib;
/** the original plugin definition */
definition: SandyPluginDefinition;
/** the plugin instance api as used inside components and such */
instanceApi: any;
/** the device owning this plugin */
readonly device: Device;
/** the unique plugin key for this plugin instance, which is unique for this device/app?/pluginId combo */
readonly pluginKey: string;
activated: boolean;
destroyed: boolean;
private serverAddOnStarted;
private serverAddOnStopped;
readonly events: EventEmitter<string | symbol, any>;
initialStates?: Record<string, any>;
readonly rootStates: Record<string, Persistable>;
lastDeeplink?: any;
exportHandler?: StateExportHandler;
importHandler?: StateImportHandler;
menuEntries: NormalizedMenuEntry[];
logListeners: Symbol[];
crashListeners: Symbol[];
readonly instanceId: number;
constructor(serverAddOnControls: ServerAddOnControls, flipperLib: FlipperLib, definition: SandyPluginDefinition, device: Device, pluginKey: string, initialStates?: Record<string, any>);
protected initializePlugin(factory: () => any): void;
protected createBasePluginClient(): BasePluginClient<any, any>;
activate(): void;
deactivate(): void;
destroy(): void;
triggerDeepLink(deepLink: unknown): void;
exportStateSync(): {
[k: string]: any;
};
private serializeRootStates;
exportState(idler: Idler, onStatusMessage: (msg: string) => void): Promise<Record<string, any>>;
isPersistable(): boolean;
protected assertNotDestroyed(): void;
abstract toJSON(): string;
protected abstract serverAddOnOwner: string;
protected startServerAddOn(): void;
protected stopServerAddOn(): void;
}
export {};
//# sourceMappingURL=PluginBase.d.ts.map