papi-dts
    Preparing search index...

    Interface CommandHandlers

    Function types for each command available on the papi. Each extension can extend this interface to add commands that it registers on the papi with papi.commands.registerCommand.

    Note: Command names must consist of two strings separated by at least one period. We recommend one period and lower camel case in case we expand the api in the future to allow dot notation.

    An extension can extend this interface to add types for the commands it registers by adding the following to its .d.ts file:

    declare module 'papi-shared-types' {
      export interface CommandHandlers {
        'myExtension.myCommand1': (foo: string, bar: number) => string;
        'myExtension.myCommand2': (foo: string) => Promise<void>;
      }
    }
    interface CommandHandlers {
        "platform.about": () => Promise<void>;
        "platform.closeOpenUsersnapForm": () => Promise<void>;
        "platform.createWindow": () => Promise<void>;
        "platform.getFocusedWindowId": () => Promise<undefined | string>;
        "platform.getLogFileContent": () => Promise<string>;
        "platform.getOSPlatform": () => Promise<undefined | string>;
        "platform.getWindows": () => Promise<WindowSummary[]>;
        "platform.goToNextBook": () => Promise<void>;
        "platform.goToNextChapter": () => Promise<void>;
        "platform.goToNextVerse": () => Promise<void>;
        "platform.goToPreviousBook": () => Promise<void>;
        "platform.goToPreviousChapter": () => Promise<void>;
        "platform.goToPreviousVerse": () => Promise<void>;
        "platform.isFullScreen": () => Promise<boolean>;
        "platform.isUsersnapFormCurrentlyOpen": () => Promise<boolean>;
        "platform.moveWebViewToNewWindow": (
            webViewId: string,
            isUserRequested?: boolean,
        ) => Promise<string>;
        "platform.moveWebViewToWindow": (
            webViewId: string,
            targetWindowId: string,
            isUserRequested?: boolean,
        ) => Promise<string>;
        "platform.navigateLeftInReferenceHistory": () => Promise<boolean>;
        "platform.navigateRightInReferenceHistory": () => Promise<boolean>;
        "platform.openBookChapterControl": () => Promise<void>;
        "platform.openDeveloperDocumentationUrl": () => Promise<void>;
        "platform.openProjectSettings": (webViewId: string) => Promise<void>;
        "platform.openSettings": (webViewId?: string) => Promise<void>;
        "platform.openTermsOfService": () => Promise<void>;
        "platform.openUserSettings": () => Promise<void>;
        "platform.openWindow": (url: string) => Promise<void>;
        "platform.quit": () => Promise<void>;
        "platform.restart": () => Promise<void>;
        "platform.restartExtensionHost": () => Promise<void>;
        "platform.showOnboardingTour": () => Promise<void>;
        "platform.usersnapReportIssue": () => Promise<void>;
        "platform.usersnapSubmitIdea": () => Promise<void>;
        "platform.zoomIn": () => Promise<void>;
        "platform.zoomOut": () => Promise<void>;
        "test.addMany": (...nums: number[]) => number;
        "test.echo": (message: string) => string;
        "test.echoExtensionHost": (message: string) => Promise<string>;
        "test.throwError": (message: string) => void;
        "test.throwErrorExtensionHost": (message: string) => void;
    }
    Index

    Properties

    platform.about platform.closeOpenUsersnapForm platform.createWindow platform.getFocusedWindowId platform.getLogFileContent platform.getOSPlatform platform.getWindows platform.goToNextBook platform.goToNextChapter platform.goToNextVerse platform.goToPreviousBook platform.goToPreviousChapter platform.goToPreviousVerse platform.isFullScreen platform.isUsersnapFormCurrentlyOpen platform.moveWebViewToNewWindow platform.moveWebViewToWindow platform.navigateLeftInReferenceHistory platform.navigateRightInReferenceHistory platform.openBookChapterControl platform.openDeveloperDocumentationUrl platform.openProjectSettings platform.openSettings platform.openTermsOfService platform.openUserSettings platform.openWindow platform.quit platform.restart platform.restartExtensionHost platform.showOnboardingTour platform.usersnapReportIssue platform.usersnapSubmitIdea platform.zoomIn platform.zoomOut test.addMany test.echo test.echoExtensionHost test.throwError test.throwErrorExtensionHost

    Properties

    "platform.about": () => Promise<void>

    Open a dialog that displays essential information about the application

    "platform.closeOpenUsersnapForm": () => Promise<void>

    Call close function for Usersnap forms known to the application

    "platform.createWindow": () => Promise<void>

    Create a new application window

    This command is unstable and may change or disappear without notice

    "platform.getFocusedWindowId": () => Promise<undefined | string>

    Get the ID of the currently focused window, or undefined if no window is focused

    This command is unstable and may change or disappear without notice

    "platform.getLogFileContent": () => Promise<string>

    Get the current log file content for debugging purposes

    "platform.getOSPlatform": () => Promise<undefined | string>

    Get the operating system platform

    "platform.getWindows": () => Promise<WindowSummary[]>

    List every open window with the title it is currently showing, for offering the user a choice of window. Titles follow each window's own content, so two windows showing the same thing carry the same label and nothing distinguishes them.

    This command is unstable and may change or disappear without notice

    "platform.goToNextBook": () => Promise<void>

    Navigate the active scroll group to the next book (chapter 1, verse 1)

    This command is unstable and may change or disappear without notice

    "platform.goToNextChapter": () => Promise<void>

    Navigate the active scroll group to the next chapter (rolls into the next book)

    This command is unstable and may change or disappear without notice

    "platform.goToNextVerse": () => Promise<void>

    Navigate the active scroll group to the next verse

    This command is unstable and may change or disappear without notice

    "platform.goToPreviousBook": () => Promise<void>

    Navigate the active scroll group to the previous book (chapter 1, verse 1)

    This command is unstable and may change or disappear without notice

    "platform.goToPreviousChapter": () => Promise<void>

    Navigate the active scroll group to the previous chapter (rolls into the previous book)

    This command is unstable and may change or disappear without notice

    "platform.goToPreviousVerse": () => Promise<void>

    Navigate the active scroll group to the previous verse

    This command is unstable and may change or disappear without notice

    "platform.isFullScreen": () => Promise<boolean>

    If the browser window is in full screen

    "platform.isUsersnapFormCurrentlyOpen": () => Promise<boolean>

    Check if a Usersnap form is currently open

    "platform.moveWebViewToNewWindow": (
        webViewId: string,
        isUserRequested?: boolean,
    ) => Promise<string>

    Move a web view to a window created for it.

    A move closes the web view in the window that holds it and reopens it — same useWebViewState state — in the target window. Consumers see a close event in the source and an open event in the target, and the web view controller is disposed and re-created: a held controller reference must be re-acquired after a move. The returned id is the authoritative id of the web view after the move — the same id as webViewId, since a web view keeps the id it was minted with for its whole life, across any number of moves — so use the returned id for anything after the move. In Simple mode — single-window by design — there is no other window to move to, and this does nothing.

    A failed move says where it left the web view, as a machine-readable marker at the front of the error message: [webViewMoveFailure:<where>], where <where> is reopened-in-source-window (nothing about where it lives changed), reopened-in-focused-window (it did move, just not to the window that was asked for), not-reopened (it is open in no window, and only the log holds what it was), reached-new-window-unconfirmed (the window created for the move is holding it, but the move could not get that confirmed), possibly-closed (taking it out of its window is what failed, so where it is cannot be told), or already-moving (this call was refused before it started, because another move of the same web view was already running — the web view is wherever that other move leaves it). The marker rides in the message because a rejection that crosses processes reaches its caller as a code and a message and nothing else. A failure decided before the move touches the web view for any other reason — an unknown target window, a target on its way out, an interface mode that could not be read — carries no marker. Strip the marker before showing the message to a user — it is there to be classified on, not read.

    Type declaration

      • (webViewId: string, isUserRequested?: boolean): Promise<string>

      • Parameters

        • webViewId: string

          Web view to move

        • OptionalisUserRequested: boolean

          Whether a person in this app asked for this move — a tab's own context menu did. Defaults to false, which is the right answer for an extension moving a view on its own: the window that appears does not take the foreground, so it cannot interrupt whatever the user is doing. Pass true only from a control the user operated

        Returns Promise<string>

        Authoritative id of the web view in its new window — the same id as webViewId; see above The isUserRequested parameter is new; the rest of this command is long-established.

    "platform.moveWebViewToWindow": (
        webViewId: string,
        targetWindowId: string,
        isUserRequested?: boolean,
    ) => Promise<string>

    Move a web view to an existing window, named by its window id (see papi.window.getWindowId() for the id of the window the caller is in, or platform.getFocusedWindowId for whichever window the user is looking at). Ids are platform-assigned and never reused within a profile.

    Same semantics as platform.moveWebViewToNewWindow — including the marker a failed move carries to say where it left the web view — and: moving a web view to the window it is already in does nothing, and naming a window that does not exist is an error that leaves the web view where it is.

    Type declaration

      • (
            webViewId: string,
            targetWindowId: string,
            isUserRequested?: boolean,
        ): Promise<string>

      • Parameters

        • webViewId: string

          Web view to move

        • targetWindowId: string

          Window to move it to

        • OptionalisUserRequested: boolean

          Whether a person in this app asked for this move — a tab's own context menu did. Defaults to false, which is the right answer for an extension moving a view on its own. A target window the platform opened without activation and the user has not yet been in stays backgrounded unless this is true: naming it is the user asking to go there, which is what raises it. Pass true only from a control the user operated

        Returns Promise<string>

        Authoritative id of the web view in its new window — the same id as webViewId; see platform.moveWebViewToNewWindow The isUserRequested parameter is new; the rest of this command is long-established.

    "platform.navigateLeftInReferenceHistory": () => Promise<boolean>

    Navigate the reference history in the physical "left" direction. Acts on the same scroll group the top toolbar follows (the active web view's scroll group), so a keyboard shortcut and the on-screen history buttons can never disagree. The window supplies its UI layout direction and the physical direction is resolved to a logical one against it: left = back in LTR, forward in RTL (the pair swaps, physical-direction preserving). The main-process keyboard handler dispatches this directly so it never needs to know the UI direction or the active scroll group.

    Type declaration

      • (): Promise<boolean>

      • Returns Promise<boolean>

        true if navigation happened; false when there is no history in that direction or the active web view has no scroll group (a detached ref)

    If there is no window to navigate in, or the window could not say what to navigate. false reports only that there was nowhere to move to, never that the command could not be run.

    "platform.navigateRightInReferenceHistory": () => Promise<boolean>

    Navigate the reference history in the physical "right" direction. Acts on the same scroll group the top toolbar follows (the active web view's scroll group), so a keyboard shortcut and the on-screen history buttons can never disagree. The window supplies its UI layout direction and the physical direction is resolved to a logical one against it: right = forward in LTR, back in RTL (the pair swaps, physical-direction preserving). The main-process keyboard handler dispatches this directly so it never needs to know the UI direction or the active scroll group.

    Type declaration

      • (): Promise<boolean>

      • Returns Promise<boolean>

        true if navigation happened; false when there is no history in that direction or the active web view has no scroll group (a detached ref)

    If there is no window to navigate in, or the window could not say what to navigate. false reports only that there was nowhere to move to, never that the command could not be run.

    "platform.openBookChapterControl": () => Promise<void>

    Open the appropriate Book Chapter Control (the active tab's if it shows one, else the top toolbar's) and focus its input, ready for typing a reference

    This command is unstable and may change or disappear without notice

    "platform.openDeveloperDocumentationUrl": () => Promise<void>

    Open a browser to the platform's OpenRPC documentation

    "platform.openProjectSettings": (webViewId: string) => Promise<void>

    3 December 2024. Renamed to platform.openSettings

    "platform.openSettings": (webViewId?: string) => Promise<void>
    "platform.openTermsOfService": () => Promise<void>

    Open the Terms of Service document that ships beside the application - the terms the distributed application is licensed to the user under, rather than this repository's AGPL source (see LICENSING.md).

    The document is a self-contained HTML file, shown in a window the application owns rather than handed to the operating system. One window at a time: a second request focuses the one already open. Every link in the document leaves through the browser, so the window only ever shows the document.

    If the document could not be loaded. A caller that offers this as a link needs to be able to tell the user the document did not open, so the failure is reported rather than only logged.

    "platform.openUserSettings": () => Promise<void>

    3 December 2024. Renamed to platform.openSettings

    "platform.openWindow": (url: string) => Promise<void>

    Open a link in a new browser window. Like window.open in the frontend with target='_blank' Consider using a visual indication along with this. E.g. for a menu download the https://lucide.dev/icons/external-link icon, add it to your extension's assets folder and use it like

    • "iconPathAfter": "papi-extension://<yourExtension>/assets/icons/external-link.svg". We plan to provide a common set of icons via an API in the future.

    For a button that opens external urls add

    • aria-label="{localizedStrings['%ariaLabel_opensInBrowser%']}"
    • Lucide icon <ExternalLink />
    "platform.quit": () => Promise<void>

    Shut down the application

    "platform.restart": () => Promise<void>

    Restart the application

    "platform.restartExtensionHost": () => Promise<void>
    "platform.showOnboardingTour": () => Promise<void>

    Show the orientation tour again from its first stop, in the window the user is working in. Available in both interface modes: in Power mode the tour reduces to the stops whose anchors exist there, which today is the toolbar's profile button.

    This command is unstable and may change or disappear without notice

    "platform.usersnapReportIssue": () => Promise<void>

    Open Usersnap feedback form to report an issue

    "platform.usersnapSubmitIdea": () => Promise<void>

    Open Usersnap feedback form to submit an idea

    "platform.zoomIn": () => Promise<void>

    Increase the zoom level of the entire UI

    "platform.zoomOut": () => Promise<void>

    Decrease the zoom level of the entire UI

    "test.addMany": (...nums: number[]) => number
    "test.echo": (message: string) => string
    "test.echoExtensionHost": (message: string) => Promise<string>
    "test.throwError": (message: string) => void
    "test.throwErrorExtensionHost": (message: string) => void

    Settings

    Member Visibility

    On This Page

    Properties
    platform.aboutplatform.closeOpenUsersnapFormplatform.createWindowplatform.getFocusedWindowIdplatform.getLogFileContentplatform.getOSPlatformplatform.getWindowsplatform.goToNextBookplatform.goToNextChapterplatform.goToNextVerseplatform.goToPreviousBookplatform.goToPreviousChapterplatform.goToPreviousVerseplatform.isFullScreenplatform.isUsersnapFormCurrentlyOpenplatform.moveWebViewToNewWindowplatform.moveWebViewToWindowplatform.navigateLeftInReferenceHistoryplatform.navigateRightInReferenceHistoryplatform.openBookChapterControlplatform.openDeveloperDocumentationUrlplatform.openProjectSettingsplatform.openSettingsplatform.openTermsOfServiceplatform.openUserSettingsplatform.openWindowplatform.quitplatform.restartplatform.restartExtensionHostplatform.showOnboardingTourplatform.usersnapReportIssueplatform.usersnapSubmitIdeaplatform.zoomInplatform.zoomOuttest.addManytest.echotest.echoExtensionHosttest.throwErrortest.throwErrorExtensionHost