popclip.d.ts

/*
This is a TypeScript definitions file for PopClip's JavaScript interface.
This file lets TypeScript-aware editors provide auto-complete and
syntax checking for both JavaScript and TypeScript code.

One way to point your editor to this file is to add a line like this to
the top of your JS or TS:
/// <reference path="(...insert path to...)/popclip.d.ts" />
*/

/**
 * An object mapping language codes to strings. See [[LocalizableString]].
 *
 * #### Notes
 *
 * An `en` string is required, as the default fallback, and it should usually
 * contain a string in US English, which is the macOS default.
 *
 * The predefined languages in this interface definition are the ones that
 * PopClip currently ships with translations for.
 * But you can include other languages too.
 * For example you can include `en-GB` or `en-CA` string to have different
 * regional spellings.
 */
declare interface StringTable {
  /** English (US) language string. */
  en: string
  /** Danish language string. */
  da?: string
  /** German language string. */
  de?: string
  /** Spanish language string. */
  es?: string
  /** French language string. */
  fr?: string
  /** Italian language string. */
  it?: string
  /** Japanese language string. */
  ja?: string
  /** Korean language string. */
  ko?: string
  /** Dutch language string. */
  nl?: string
  /** Brazilian Portuguese language string. */
  'pt-BR'?: string
  /** Russian language string. */
  ru?: string
  /** Vietnamese language string. */
  vi?: string
  /** Simplified Chinese language string. */
  'zh-Hans'?: string
  /** Traditional Chinese language string. */
  'zh-Hant'?: string
  /** Any other strings. */
  [code: string]: string
}

/**
 * A type to represent a localizable string.
 *
 * #### Notes
 *
 * The value may be either a string or an object.
 * If you supply a string, that string is used.
 * If you supply a [[StringTable]] object, PopClip will
 * display the string for the user's preferred language if possible, with fallback to the `en` string.
 *
 * #### Example
 * ```js
 * option.label = "Color" // just use this string
 * option.label = { en: "Color", "en-GB": "Colour", fr: "Couleur", "zh-Hans": "颜色" }
 */
declare type LocalizableString = string | StringTable

/**
 * A string with a special format to declare an icon. Used for {@link Extension.icon} and {@link Action.icon}.
 *
 * Icons may be specified in a few different ways:
 *
 * * **Image file:** A string with suffix `.png` or `.svg` matching the name of an image file in the extension package. Images must be in either PNG or SVG format.
 * The icons should be square and monochrome, black, on a transparent background. You can use opacity to create shading.
 * PNG icons should be at least 256x256 pixels in size.
 *
 * * **SF Symbol:** A string of the form `symbol:<symbol name>` specifies an [SF Symbols](https://sfsymbols.com) name, for example `symbol:flame`.
 * Symbols are available starting on macOS 11.0 and above, but some symbols require higher macOS versions, as indicated in the
 * "Availability" panel in Apple's SF Symbols browser app.
 *
 * * **Text icon:** A string of the form `text:<text icon specifier>` instructs PopClip to generate a text-based icon, as described below.
 *
 * ### Text icons
 *
 * Text-based icons can up to three characters, on their own or within an enclosing shape. The enclosing shape is specified using different kinds of brackets around the text. The easiest way to explain is probably by example:
 *
 * * `text:A` - the letter A on its own
 *
 * * `text:(1)` - the digit 1 in an outline circle
 *
 * * `text:((本))` - the character 本 in a filled circle
 *
 * * `text:[xyz]` - the characters xyz in an outline square
 *
 * * `text:[[!]]` - the character ! in a filled square
 *
 */
declare type IconString = string

/**
 * Represents the state of the four modifier keys. The value is true when the key is held down.
 * See {@link PopClip.modifiers}.
 */
declare interface Modifiers {
  /** Shift (⇧) key state. */
  shift: boolean
  /** Control (⌃) key state. */
  control: boolean
  /** Option (⌥) key state. */
  option: boolean
  /** Command (⌘) key state. */
  command: boolean
}

/**
  * A requirement is specified in the {@link Action.requirements} array as a string.
  * The possible strings are:
  *
  * | Specifier     | Condition                                                  |
  * |---------------|------------------------------------------------------------|
  * |`text`|One or more characters of text must be selected. |
  * |`copy`| A synonym for `text`, for backwards compatibility.|
  * |`cut`| Text must be selected and the app's Cut command must be available.|
  * |`paste`|The app's Paste command must be available.|
  * |`formatting`|The selected text control must support formatting. (PopClip makes its best guess about this, erring on the side of a false positive.)|
  * |`weburl`|The text must contain exactly one web URL (http or https).|
  * |`weburls`|The text must contain one or more web URLs (http or https).|
  * |`email`|The text must contain exactly one email address.|
  * |`emails`|The text must contain one or email addresses.|
  * |`path`|The text must be a local file path, and it must exist on the local file system.|
  * |`option-foo=bar`|The current value of the option named `foo` must be equal to the string `bar`. (Boolean values match against strings `0` and `1`.)|
  *
  * A requirement can also be **negated** by prefixing `!`, to specify that the requirement must _not_ be met.
  *
  * #### Example
  * ```js
  * ["paste", "!weburls", "option-goFishing=1"]
  * ```
  */
 declare type Requirement =
 | 'text' | 'copy' | 'cut' | 'paste' | 'formatting' | 'url' | 'urls' | 'email' | 'emails' | 'path'
 | `option-${string}=${string}`

 /** Negated form of [[Requirement]]. */
 declare type NegatedRequirement = `!${Requirement}`

 /**
  * Strings which can be used to specify the [[before]] action.
  */
 declare type BeforeStep = 'cut' | 'copy' | 'paste' | 'paste-plain' | 'popclip-appear' | 'show-status'

 /**
  * Strings which can be used to specify the [[after]] action.
  */
 declare type AfterStep = BeforeStep | 'copy-result' | 'paste-result' | 'show-result' | 'preview-result'

/**
 * Declares information about an app or website that this extension interacts with.
 */
declare interface AssociatedApp {
  /** Name of the app. Fo example "Scrivener" */
  name: string

  /**
   * Web page where user can obtain the app, e.g. "https://www.literatureandlatte.com/scrivener".
   *
   * PopClip will link to this page if the "missing app" dialog is shown. The link is also used
   * this in the online extension listing.
   */
  link: string

  /**
   * Indicates whether PopClip should check for the presence of the app on the computer. If not found,
   * PopCLip will display a message prompting the user to install the app. Default is no. Not applicable for websites.
   */
  checkInstalled?: boolean

  /**
   * List of possible bundle identifiers of this app.
   *
   * PopCLip uses this list when checking for the presence of the app. Include here all application variants
   * that work with this extension. In the simplest case there may
   * be just one bundle ID, but an app may have alternative bundle IDs such as for free/pro variants,
   * an App Store version, a stand-alone version, a Setapp version, and so on.
   */
  bundleIdentifiers?: string[]
}

/**
 * A population function dynamically generates the actions for the extension. See [[Extension.actions]].
 * @param input The selected text and related properties. (Same object as [[PopClip.selection]].)
 * @param options Current values of the options for this extension. (Same object as [[PopClip.options]].)
 * @param context Information about the context surrounding the selection. (Same object as [[PopClip.context]].)
 * @returns A single action, an array of actions.
 */
 declare type PopulationFunction = (input: Input, options: Options, context: Context) => Action[] | Action | null

/**
 * Object returned by [[Extension.auth]] when there is an authentication flow to kick off
 */
declare type AuthFlowFunction = (url: string, params?: {[string]: string | undefined}, expect?: string[]) => Promise<any>

/** Credentials used in auth function */
declare interface AuthInfo {
  /** Value of `username` option (will be empty string if none defined) */
  username: string
  /** Value of `password` option (will be empty string if none defined) */
  password: string
  /** An appropriate value to use as the redirection URL in authorization flows for this extension.
   * Example output:
   * `http://localhost:58906/callback/com.pilotmoon.popclip.extension.todoist/auth`
   */
  redirect: string
  /** Extension display name */
  name: string
  /** Extension identifier */
  identifier: string
}

/**
 * Function signature of the [[Extension.auth]] method.
 */
declare type AuthFunction = (info: AuthInfo, flow: AuthFlowFunction) => Promise<string>

/**
 * Boolean flags that define certain properties of actions.
 * @category Definition
 */
declare interface ActionFlags {
  /**
   * Whether PopClip will capture HTML and Markdown content for the selection. Default is no.
   *
   * #### Notes
   * The HTML can be accessed in the [[Selection.html]] property, and the Markdown
   * can be accessed in the [[Selection.markdown]] property.
   *
   * If the selection is not HTML-backed, PopClip will generate HTML from any available RTF or plain text
   * content.
   */
  captureHtml?: boolean

  /**
   * Whether PopClip will capture RTF (Rich Text Format) content for the selection. Default is no.
   *
   * #### Notes
   * Captured RTF can be accessed in the [[Selection.items]] property under the `public.rtf` key.
   */
  captureRtf?: boolean

  /** Whether PopClip's popup should stay on screen after clicking this action's button. Default is no.
   *
   * #### Notes
   * An example of this in use is the Formatting extension.
   */
  stayVisible?: boolean

  /**
   * Whether the action's icon should be displayed in its original color rather than monochrome.
   */
  preserveImageColor?: boolean

  /**
   * Whether the pasteboard should be restored to its original state after `paste-result`.
   */
  restorePasteboard?: boolean
}

/**
 * Properties common to ActionObject, ActionFunction and Extension
 */
declare interface ActionProperties extends ActionFlags {

  /**
    * A unique identifying string.
    *
    * #### Notes
    *
    * An identifier for an action can be any string of your choosing.
    *
    * An identifier for the extension itself, if provided, should ideally be globally unique.
    *
    * I suggest using a reverse DNS-style identifier. For example `com.example.myextension`.
    *
    * If you don't have your own domain name, you can use anything you like — it doesn't matter, as long as it is unique.
    *
    * Do not use the `com.pilotmoon.` prefix for your own extension.
    */
  identifier?: string

  /**
     * The action's title. The title is displayed in the action button if there is no icon.
     * For extensions with icons, the title is displayed in the tooltip.
     *
     * If no title is defined here, the extension's [`[name]] will be used, if any.
    */
  title?: LocalizableString

  /**
     * A string to define the action's icon. See [[IconString]].
     *
     * If no icon is defined here, the extension's {@link Extension.icon | icon} will be used, if any.
     * Setting to `null` explicitly sets the action to have no icon.
     */
  icon?: IconString | null

  /**
    * An array of conditions which must be met for this action to appear — see [[Requirement]].
    *
    * * If no array is specified here, the action takes the value of [[Extension.requirements]].
    * * If no array is specified there either, the action takes the default value `["text"]`.
    *
    * #### Notes
    *
    * When multiple conditions are specified, all of them must be satisfied.
    *
    * An empty array (`[]`) indicates no requirements at all, meaning the action will always appear.
    *
    * This property has no effect on dynamically generated actions.
    */
  requirements?: Array<Requirement | NegatedRequirement>

  /**
    * Array of bundle identifiers for which the extension should appear. The action will only
    * appear if PopCLip is used in one of the specified apps.
    *
    * This property has no effect on dynamically generated actions.
    */
  requiredApps?: string[]

  /**
    * Array of bundle identifiers for which the extension should not appear. The action will not
    * appear if PopClip is used in any of the specified apps.
    *
    * This property has no effect on dynamically generated actions.
    */
  excludedApps?: string[]

  /**
    * A regular expression to decide whether this action appears in the popup.
    *
    * * If no regex is specified here, the action takes the value of [[Extension.regex]].
    * * If no regex is specified there either, the action will match any input.
    *
    * #### Notes
    *
    * You may express the value either as a
    * [JavaScript regular expression literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)
    * (or otherwise constructed `RegExp` object), or as a string.
    *
    * * If you supply a `RegExp` it will be evaluated in the JavaScript engine.
    * * If you supply a string it will be evaluated by macOS natively using the `NSRegularExpression` API (same as for 'classic' PopClip extensions).
    *
    * If the regex matches the selected text, the action will be shown in the popup and
    * the first occurrence of the matched text is accessible later via {@link Input.matchedText | matchedText}.
    *
    * If there is no match, the action is excluded from the popup.
    *
    * The regex's `lastIndex` is reset before and after each invocation, so the `g` (global) and `y` (sticky) flags have no effect.
    *
    * This property has no effect on dynamically generated actions.
    *
    * #### Example
    * ```js
    * regex = /abc/i   // Example regex 'abc' with 'i' (case insensitive) flag
    *                  // Matches abc, ABC, Abc, etc.
    * ```
    */
  regex?: RegExp | string

  /**
  * Declares the application or website associated with this action, if any.
  */
  app?: AssociatedApp

  /**
  * An optional step to peform before the main action.
  */
  before?: BeforeStep

  /**
  * An optional step to peform after the main action.
  */
  after?: AfterStep

  // fpr benefit of JSON Schema
  shortcutName?: string
  serviceName?: string
  url?: string
  keyCombo?: string | number
  keyCombos?: Array<string | number>
  applescript?: string
  applescriptFile?: string
  applescriptCall?: {
    file: string
    handler: string
    parameters?: string[]
  }
  shellScriptFile?: string
  interpreter?: string
  javascript?: string
  javascriptFile?: string
}

/**
 * A callable object, with additional properties to define its title, icon and other properties.
 *
 * @category Definition
 */
declare interface ActionFunction extends ActionProperties {
  /**
    * An action function is called when the user clicks the action button in PopClip. This is where
    * the extension does its main work.
    * @param input The selected text and related properties. (Same object as [[PopClip.selection]].)
    * @param options Current values of the options for this extension. (Same object as [[PopClip.options]].)
    * @param context Information about the context surrounding the selection. (Same object as [[PopClip.context]].)
    */
  (input: Input, options: Options, context: Context): Promise<string | null> | string | null
}

/**
 * An alternative way to define as an action, as a non-callable object with a `code` member.
 * If code is omitted, displays as disabled title/icon only.
 */
declare interface ActionObject extends ActionProperties {
  /** Same function signature as [[ActionFunction]] */
  code?: (input: Input, options: Options, context: Context) => Promise<string | null> | string | null
}

/**
 * An action can be defined using either the callable object or non-callable object form.
 */
declare type Action = ActionFunction | ActionObject

// included for JSON Schema
declare type Entitlement = 'network' | 'dynamic'

/**
 * The Extension object defines the PopClip extension.
 *
 * You create this in Config.js and export it with `define()`.
 *
 * Any properties omitted from the extension object in Config.js (apart from [[action]] and [[actions]])
 * fall back to the equivalent value in the Config.json file, if it is present.
 *
 *
 * #### Examples
 *
 * *Simple extension* — The following Config.js defines a complete extension:
 *
 * * Config.js
 * ```js
 *   define({
 *     identifier: "com.example.my-extension",
 *     name: "My Extension",
 *     action: function(selection) {
 *       popclip.showText("Your text is: " + selection.text)
 *     }
 *   })
 * ```
 *
 * *Example with Config.json* — The previous example is equivalent to:
 *
 * * Config.json:
 * ```json
 * {
 *     "identifier": "com.example.my-extension",
 *     "name": "My Extension",
 * }
 * ```
 *
 * * Config.js:
 * ```js
 *   define({
 *     action: function(selection) {
 *       popclip.showText("Your text is: " + selection.text)
 *     }
 *   })
 * ```
 *
 *
 * @category Definition
 */
declare interface Extension extends ActionProperties {

  /**
   * The display name of this extension.
   *
   * If omitted, the name is taken from the Config.json file, or else auto-generated from the package name.
   */
  name?: LocalizableString

  /**
     * Defines the user-configurable options for this extension.
     */
  options?: Option[]

  /**
   * If you define this function then PopClip will display a 'sign in' button in the options UI. When the use clicks Sign In,
   *
   * If the sign in needs a username and password, you'll also need to define `username` and `password` options. PopClip will then pass the values
   * of those options in the info parameter. */
  auth?: AuthFunction

  /**
     * Define the actions to go in PopClip's popup. This can be an array or a function.
     *
     * * If it's an array, the supplied actions are used in the popup, subject to meeting the
     * requirements and regex conditions.
     *
     * * If it's a function, it is called by PopClip to dynamically populate the popup with actions from this extension.
     * Setting requirements and regex keys has no effect on dynamic actions — the function itself is responsible for deciding what actions to show.
     */
  actions?: Action[] | PopulationFunction

  /**
     * Simplified property to define a single action.
     */
  action?: Action

  /**
   * A unit test function for this extension. Should throw an error if test fails.
   */
  test?: () => void

  // the following are included for the benefit of the JSON Scheme generation
  popclipVersion?: number
  macosVersion?: string
  entitlements?: Entitlement[]
  module?: string
}

/**
 * Defines a single extension option.
 *
 * @category Definition
 */
declare interface Option {
  /**
   * An identifying string for this option.
   */
  identifier: string

  /**
   * The kind of option, one of:
   *  * `string`: a text box for free text entry,
   *  * `boolean`: a check box,
   *  * `multiple`: multiple-choice drop-down with predefined options,
   *  * `password`: a password entry field (passwords are stored in user's keychain instead of preferences),
   *  * `heading`: adds a heading in the user interface, but does not actually define an option
   */
  type: 'string' | 'boolean' | 'multiple' | 'password' | 'heading'

  /**
   * A short label for this option.
   */
  label: LocalizableString

  /**
   * An optional longer explanantion of this option, to be shown in the UI.
   */
  description?: LocalizableString

  /**
   * The default value of the option. If ommitted, `string` options default to the empty string,
   * `boolean` options default to true, and `multiple` options default to the top item in the list.
   * A `password` field may not have a default value.
   */
  defaultValue?: string | boolean

  /**
   * The possible values for a `multiple` option.
   */
  values?: string[]

  /**
   * Display names corresponding to the entries in the [[values]] array. These are shown in the option UI.
   * If ommitted, the raw value strings are shown instead.
   */
  valueLabels?: LocalizableString[]

  /**
   * An icon for this option. It is only displayed for boolean options, next to the check box. See [[IconString]].
   */
  icon?: IconString

  /*
   * If true, this option will be hidden in the prefs window. Default is false.
   */
  hidden?: boolean

  /*
   * If true, this option will be be inset to the right of its label, instead of below it. Default is false.
   */
  inset?: boolean
}

/** Represents a generic range, as a location and length */
declare interface Range {
  location: number
  length: number
}
/** An array of strings with an addiontal `ranges` property defining the source of the data in the orignal string. */
declare interface RangedStrings extends Array<string> {
  ranges: Range[]
}

/**
 * Input defines properties to access the input text contents.
 */
declare interface Input {
  /**
     * The plain text selected by the user. If there is no selected text, perhaps because the user invoked PopClip by a long press,
     * this will be the empty string.
     */
  text: string

  /**
     * If the action specified {@link Action.requirements | requirements} or a {@link Action.regex | regex} to match the input, this will be the matching part of the text.
     * Otherwise, it will be the same string as [[text]].
     */
  matchedText: string

  /*
     * If the action specified a {@link Action.regex | regex} to match the input, this will be the full result of the the match.
     *
     * You can use this to access any capture groups from the regex.
     * The value is a return value from JavaScript's [RegExp.prototype.exec()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) method.
     *
     * #### Example
     * ```js
     * // text: "apple", regex: /.(.)/
     * selection.regexResult[0] // "ap" (full match)
     * selection.regexResult[1] // "p" (capture group 1)
     * ```
     */
  regexResult?: any

  /**
     * HTML. (docs todo)
     */
  html: string

  /**
   * XHTML. (docs todo)
   */
  xhtml: string

  /**
     * Markdown. (docs todo)
     */
  markdown: string

  /**
     * RTF. (docs todo)
     */
  rtf: string

  /**
     * Data of various kinds, that PopClip detected in the selected text.
     */
  data: {
    /** HTTP ot HTTPS urls. */
    urls: RangedStrings
    /** Other protocols or app urls e.g. ftp:, omnifocus:, craftdocs: etc. (PopClip has a pre-defined allowlist
         * for these "other" URL schemes.) */
    nonHttpUrls: RangedStrings
    /** Email addresses. */
    emails: RangedStrings
    /** A local file path. The file path must be for a directory or file that exists. */
    paths: RangedStrings
  }

  /**
   * Unprocessed selection contents indexed by UTI.
   */
  content: PasteboardContent
}

/**
*  Properties relating the context surrounding the selected text.
*/
declare interface Context {
  /**
     * Indicates whether the text area supports formatting.
     *
     * PopClip can't always detect whether the text area supports formatting or not, in which case
     * it will err on the side of a false positive.
     */
  hasFormatting: boolean

  /**
    * This property is true iff the Paste command is enabled in the current app.
    */
  canPaste: boolean

  /**
    * This property is true iff text was selected.
    */
  canCopy: boolean

  /**
    * This property is true iff text was selected and the app's Cut command is enabled.
    */
  canCut: boolean

  /**
   * If the current app is a compatible browser, this will be the page URL.
   */
  browserUrl: string

  /**
   * If the current app is a compatible browser, this will be the page title.
   */
  browserTitle: string

  /**
   * The name of the current app, for example `Drafts`.
   */
  appName: string

  /**
   * The bundle identitifier of the current app, for example `com.agiletortoise.Drafts-OSX`.
   */
  appIdentifier: string
}

/**
 * Represents the current values of the extension's option (that were defined in {@link Extension.options}.
 * It maps option identifier strings to the current option value. See {@link PopClip.options}, {@link Extension.actions}, [[ActionFunction]].
 *
 * The `authsecret` property has the special behaviour of thorowing an `Error` with the message 'Not signed in' if it is accessed while either
 * undefined or holding an empty string.
 */
declare interface Options {
  readonly authsecret: string
  readonly [identifier: string]: string | boolean
}

/**
* PopClip defines the methods and properties of the global [[`popclip`]] object.
*
* Methods in the **Action Methods** category are only available in an action function. If called from
* a population function, the method will throw an exception.
*
*/
declare interface PopClip {
  /*
    * A bit field representing state of the modifier keys when the action was invoked in PopClip.
    *
    * #### Notes
    *
    * Constants for the modifiers are given in {@link Util.constant | util.constant}.
    *
    * During the execution of the population function, the value of this property is always zero.
    *
    * #### Example
    *
    * ```javascript
    * // test for shift
    * if (popclip.modifierKeys & util.constant.MODIFIER_SHIFT) {
    *   ...
    * }
    *
    * // test for shift OR option
    * let combo = util.constant.MODIFIER_SHIFT|util.constant.MODIFIER_OPTION;
    * if (popclip.modifierKeys & combo) {
    *   ...
    * }
    *
    * // test for shift AND option
    * if ((popclip.modifierKeys & combo) === combo) {
    *   ...
    * }
    * ```
    */
  readonly modifierKeys: number

  /**
     * The state of the modifier keys when the action was invoked in PopClip.
     *
     * #### Notes
     * During the execution of the population function, all the modifiers will read as false.
     *
     * #### Example
     * ```js
     * if (popclip.modifiers.shift) {
     *   ...
     * }
     * ```
     *
     */
  readonly modifiers: Modifiers

  /**
     * The current selection.
     */
  readonly input: Input

  /**
     * The current context around the selection.
     */
  readonly context: Context

  /**
     * The current values of the options.
     */
  readonly options: Options

  /**
     * If the target app's Paste command is available, this method places the given string on the pasteboard
     * and then invokes the target app's Paste comand. If the `restore` flag is set in the options, it will
     * then restore the original pasteboard contents.
     *
     * If the target app's Paste command is not available, it behaves as [[copyText]] instead.
     *
     * #### Example
     *
     * ```js
     * // place "Hello" on the clipboard and invoke Paste
     * popclip.pasteText("Hello");
     * // place "Hello", then restore the original pasteboard contents
     * popclip.pasteText("Hello", {restore: true});
     * ```
     * @param text The plain text string to paste
     * @param options
     *
     * @category Action
     */
  pasteText: (text: string, options?: PasteOptions) => void

  /**
   * Paste arbitrary pasteboard content.
   */
  pasteContent: (content: PasteboardContent, options?: PasteOptions) => void

  /**
     * Places the given string on the pasteboard, and shows "Copied" notificaction to the user.
     * @param text The plain text string to copy
     * @category Action
     */
  copyText: (text: string) => void

  /**
   * Copy arbitrary pasteboard content.
   */
  copyContent: (content: PasteboardContent) => void

  // included for compatibility with old extensions
  performPaste: () => void

  /**
     * (BETA) Invokes a command in the target app.
     * @param command Either `cut`, `copy` or `paste`.
     * @param options Options for the command
     * @category Action
     */
  performCommand: (command: 'cut'|'copy'|'paste', options?: {
    /** Transformation to apply to the pasteboard contents. (Default: `none`)
     * * `none`: regular pasteboard operation
     * * `plain`: strips away everything but plain text
     */
    transform?: 'none'|'plain'
  }) => void

  /**
     * Display text inside PopClip's popup, with option to make the display a clickable button to
     * paste the text.
     * @param text The text to display. It will be truncated to 160 characters when shown.
     * @param options
     */
  showText: (text: string, options?: {
  /**
   * If `true`, and the app's Paste command is available, the displayed text will be in a cickable button,
   * which clicked, pastes the full text.
   */
    preview?: boolean
  }) => void

  /**
   * PopClip will show a checkmark symbol to indicate success.
   */
  showSuccess: () => void

  /**
   * PopClip will show an "X" symbol to indicate failure.
   */
  showFailure: () => void

  /**
   * PopClip will open the settings UI for this extension.
   *
   * #### Notes
   * If the extension has no settings, this method does nothing.
   */
  showSettings: () => void

  /**
   * Trigger PopClip to appear again with the current selection.
   */
  appear: () => void

  /**
     * Simulate a key press by the user.
     *
     * #### Examples
     *
     * ```js
     * // press the key combo ⌘B
     * popclip.pressKey('command B');
     * // press the key combo ⌥⌘H
     * popclip.pressKey('option command H');
     * // press the return key
     * popclip.pressKey('return');
     * popclip.pressKey(util.constant.KEY_RETURN); // equivalent
     * * // press option and the page down key
     * popclip.pressKey('option 0x79');
     * popclip.pressKey(0x79, util.constant.MODIFIER_OPTION); // equivalent
     * ```
     *
     * #### Notes
     *
     * Some key code and modifier constants are available in {@link Util.constant | util.constant}.
     *
     * @param key The key to press. When this parameter is a string, PopClip will interpret it as in
     * [Key Combo String Format](https://github.com/pilotmoon/PopClip-Extensions#key-combo-string-format).
     * When this parameter is a number, PopClip will use that exact key code.
     *
     * @param modifiers An optional bit mask specifiying additional modifier keys, if any.
     * @category Action
     */
  pressKey: (key: string | number, modifiers?: number) => void

  /**
     * Open a URL in an application.
     *
     * #### Choice of application
     *
     * If a target application bundle identifier is specified via the `app` option, PopClip will ask that app to open the URL.
     *
     * If no target app is specified:
     *
     * * If the URL has the http or https scheme, and the current app is a browser, the URL is opened in the current app.
     * * Otherwise, PopClip asks macOS to open the URL in the default handler for that URL type.
     *
     * #### URL encoding
     *
     * Any parameters etc. in the URL must be appropriately percent-encoded. JavaScript provides the
     * [encodeURIComponent()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
     * function for this.
     *
     * #### Example
     * ```js
     * popclip.openUrl("https://xkcd.com"); // open xckd.com in current/default browser
     * popclip.openUrl("https://xkcd.com", {app: "com.brave.Browser"}); // open xkcd.com in Brave browser
     * popclip.openUrl(`mailto:support@pilotmoon.com?subject=${encodeURIComponent("What's up?")}`); // open mailto link in the default mail application
     * ```
     *
     * @param url A well-formed URL
     * @param options
     * @category Action
     */
  openUrl: (url: string, options?: {
    /**
         * Bundle identifier of the app to open the URL with. For example `"com.google.Chrome"`.
         */
    app?: string
  }) => void
}

/**
 * The global `popclip` object encapsulates the user's current interaction with PopClip, and provides methods
 * for performing various actions. It implements [[PopClip]].
 */
declare var popclip: PopClip

// experimental rich text class
declare class RichString {
  constructor (source: string, options?: {format?: 'rtf'|'html'|'markdown', baseFont?: object, paragraphSeparation?: 'newlines'|'spacing'});
  readonly rtf: string
  readonly html: string
  font: object
  applyFont: (font: object) => void
}

/**
* A container for various utility functions and constants [[`util`]] object.
*/
declare interface Util {

  /**
     * Localize an English string into the current user interface language, if possible.
     * This will work for strings which match an existing string in PopClip's user interface.
     *
     * @param string The string to localize.
     * @return The localized string, or the original string if no localized version was avaiable.
     */
  localize: (string: string) => string

  localeInfo: {
    localeIdentifier: string
    regionCode: string
    languageCode: string
    decimalSeparator: string
    groupingSeparator: string
    currencyCode: string
    currencySymbol: string
  }

  timeZoneInfo: {
    identifier: string
    abbreviation: string
    secondsOffset: number
    daylightSaving: boolean
  }

  htmlToRtf: (html: string) => string | undefined

  /**
     * Encode a string as UTF-8 then Base-64 encode the result.
     *
     * @param string The string to encode.
     * @param options
     */
  base64Encode: (string: string, options?: {
    /**
         * Whether to encode using the URL-safe variant, with `-` and `_` substituted for `+` and `/`. Default is no.
         */
    urlSafe?: boolean
    /**
         * Whether to trim the `=`/`==` padding from the string. Default is no.
         */
    trimmed?: boolean
  }) => string

  /**
     * Decode a Base-64 string and interpret the result as a UTF-8 string.
     *
     * Accepts both standard and URL-safe variants as input. Also accepts input with or without the `=`/`==` end padding.
     * Throws an error if the input cannot be decoded as a UTF-8 string.
     *
     * @param string
     * @returns The decoded string
     */
  base64Decode: (string: string) => string

  /** Build a URL from a base URL and additional query parameters */
  buildQueryUrl: (baseUrl: string, params: {[string]: string}) => string

  /** Build a query from params object */
  buildQuery: (params: {[string]: string}) => string

  /** Parse a query into params object */
  parseQuery: (query: string) => any

  /** Decipher a JSON object that has been lightly obscured to prevent constants such as
   * API keys appearing in plaintext in the source files.
   *
   * This function will ROT13 decipher the text, apply Base64 decoding, and parse the result as JSON. */
  clarify: (obscuredString: string) => any

  /**
   * A promise-based sleep function. Included as a more convenient alternative
   * to [[setTimeout]] for performing simple delays. Call as `await sleep(1000)`.
   * @param durationMilliseconds How long to sleep in milliseconds
   */
  sleep: (durationMilliseconds: number) => Promise<void>

  /**
     * The `constant` property is a container for pre-defined constants.
     */
  readonly constant: {
    /**
         * Bit mask for the Shift (⇧) key.
         */
    readonly MODIFIER_SHIFT: 131072
    /**
         * Bit mask for the Control (⌃) key.
         */
    readonly MODIFIER_CONTROL: 262144
    /**
         * Bit mask for the Option (⌥) key.
         */
    readonly MODIFIER_OPTION: 524288
    /**
         * Bit mask for the Command (⌘) key.
         */
    readonly MODIFIER_COMMAND: 1048576
    /**
         * Key code for the Return (↵) key.
         */
    readonly KEY_RETURN: 0X24
    /**
         * Key code for the Tab (⇥) key.
         */
    readonly KEY_TAB: 0X30
    /**
         * Key code for the space bar.
         */
    readonly KEY_SPACE: 0X31
    /**
         * Key code for the Delete (⌫) key.
         */
    readonly KEY_DELETE: 0X33
    /**
         * Key code for the Escape key.
         */
    readonly KEY_ESCAPE: 0X35
    /**
         * Key code for the Left Arrow key.
         */
    readonly KEY_LEFTARROW: 0X7B
    /**
         * Key code for the Right Arrow key.
         */
    readonly KEY_RIGHTARROW: 0X7C
    /**
         * Key code for the Down Arrow key.
         */
    readonly KEY_DOWNARROW: 0X7D
    /**
         * Key code for the Up Arrow key.
         */
    readonly KEY_UPARROW: 0X7E
  }
}

/**
 * The global `util` object acts as a container for various utility functions and constants. It implements [[Util]].
 */
declare var util: Util

/**
 * Represents the raw pasteboard content, indexed by UTI. Supports string data only.
 */
declare interface PasteboardContent {
  'public.utf8-plain-text'?: string
  'public.html'?: string
  'public.rtf'?: string
  [string: string]
}

declare interface PasteOptions {
  /**
       * Whether to restore the original contents of the pasteboard after the paste
       * operation. Default is `false`.
       */
  restore?: boolean
}

/**
 * A simplified interface to the macOS pasteboard. Implemented by the global object, [[`pasteboard`]].
 */
declare interface Pasteboard {
  /**
     * Get and set the plain text content of the pasteboard.
     *
     * #### Notes
     * This property corresponds with the pasteboard type `public.utf8-plain-text`.
     *
     * When placing text on the pasteboard this way, PopClip's "Copied" notification will not appear.
     * (Typically, scripts should use [[copyText]] instead, so that the user gets the "Copied" notification.)
     *
     * The value of this property will always be a string. If there is no plain text value on the
     * pasteboard, reading this property will give an empty string (`""`).
     *
     * #### Example
     * ```js
     * let x = pasteboard.text;
     * pasteboard.text = "new text";
     * ```
     */
  text: string

  /**
   * Get and set the content of the pasteboard, of the specified types
   */
  content: PasteboardContent
}

/**
 * The global `pasteboard` object provides access to the contents of the macOS general pasteboard (i.e. the system clipboard). It implements [[Pasteboard]].
 */
declare var pasteboard: Pasteboard

/**
 * Output a string for debugging purposes. By default it is not output anywhere,  but
 * you can configure PopClip to output to the Console app by running the following command in Terminal:
 *
 * `defaults write com.pilotmoon.popclip EnableExtensionDebug -bool YES`
 *
 * then Quit and restart PopClip.
 *
 * #### Example
 * ```js
 * print("Hello, world!")
 * // print: Hello, world!
 * print(1, Math.PI, 2/3, ['a','b','c'])
 * // print: 1 3.141592653589793 0.6666666666666666 a,b,c
 * ```
 *
 * @param message One or more values, which will be coerced to strings. Multiple parameters will be separated by a space.
 */
declare function print (...args: any[]): void

/*
 * Export an object for use by another file.
 *
 * #### Notes
 *
 * The _define_ function exports an arbitrary object, which other files can  import using [[require]].
 *
 * It should be called only once in any file; if it is called more than once, only the
 * final call will have any effect.
 *
 * It is used in the extension's Config.js file to define the extension itself.
 *
 * #### Example
 * ```js
 * // greetings.js
 * function hello(name) {
 *   print("Hello, ${name}!");
 * })
 * function goodbye(name) {
 *   print("Bye, ${name}!");
 * })
 * // export these two functions. hey, we made a module!
 * define({hello, goodbye});
 *
 * ```
 *
 * Partially implements AMD protocol.
 * AMD spec: https://github.com/amdjs/amdjs-api/wiki/AMD
 */
declare function define (object: object): void
declare function define (factory: () => object): void
declare function define (dependencies: string[], factory: () => object): void
declare function define (id: string, factory: () => object): void
declare function define (id: string, dependencies: string[], factory: () => object): void

/* declare ambient module + exports for node-style exporting */
declare const module: { exports: any }
declare const exports: any

/**
 * Function called from Config.js to define the extension.
 * @param extension The extension object to pass to PopClip.
 */
declare function defineExtension (extension: Extension): void
/* note that internally, `defineExtension` is just a synonym for `define`, but it's nice to have
 * this simple version for cleaner type checking and it's easier to explain in the docs.
 */

/**
  * Import an object from another file.
  *
  * #### Notes
  * PopClip's `require()` implementation attempts to import from the following module formats:
  *
  * * AMD modules, which use `define(...)`Util.
  * * Node/CommonJS modules, which use `module.exports = ...` or `exports.name = ...`
  * * TypeScript compiled modules, which use `exports.default = ...`
  *
  * #### Notes
  *
  * Paths beginning with `./` or `../` are resolved relative to the the location of the current file.
  *
  * Otherwise, the path is resolved relative to the extensions's package root.
  * If there is no file in the extension, PopClip will look in its internal module repository.
  *
  * If no file extension is given, PopCLip will try adding the extensions `.js`, `.json` in that order.
  *
  * JSON files are parsed and returned as an object.
  *
  * #### Example
  *
  * ```js
  * // load the functions from the greeting.js file
  * const greetings = require('./greetings.js');
  * print(greetings.hello("PopClip")) // Hello, Popclip!
  *
  * // alternative using destructuring assignment
  * const {hello, goodbye} = require('./greetings.js');
  * print(goodbye("PopClip")) // Bye, Popclip!
  * ```
  *
  * @param file Path to the file to import.
  * @return The imported object.
  */
declare function require (file: string): object

/* Globals */

/**
 * Call a function after a specified time interval.
 *
 * #### Notes
 *
 * This is PopClip's own implementation of the standard
 * [setTimeout](http://developer.mozilla.org/en-US/docs/Web/API/SetTimeout) function,
 * as found in browsers.
 * Ordinarily you shouldn't need to use this. It is is mainly included for
 * compatibility with libraries that might need it.
 *
 * @param callback A function to be called after the timer expires.
 * @param timeout Timeout in milliseconds. If this parameter is omitted, a value of 0 is used,
 * @param args Additional arguments to be passed to the callback function.
 * @returns Numeric identifier for the timer which can be passed to [[clearTimeout]] to cancel it.
 * @category Timer
 */
declare function setTimeout (callback: (...args?: any) => void, timeout?: number, ...args?: any): number

/**
 * Cancels a timeout prevouly created with [[setTimeout]].
 * @param timeoutId Identifier of the timeout to cancel.
 * @category Timer
 */
declare function clearTimeout (timeoutId: number): void

/* For backward compatibility - use util.sleep instead */
declare function sleep (durationMilliseconds: number): Promise<void>
/* for library compatibility (implemented as util.base64Encode with no options) */
declare function btoa (string: string): string
/* for library compatibility (imeplemented as util.base64Decode) */
declare function atob (string: string): string
// Blob is included via a
declare const Blob: any