@theweave/api/dist/api.d.ts

This package contains the interfaces and contracts that a Holochain app UI needs to implement in order to run as a Tool in a Weave Frame like [Moss](theweave.social#tryit).

import { AgentPubKey, AppClient, CreateCloneCellRequest, CreateCloneCellResponse, DisableCloneCellRequest, EnableCloneCellRequest, EntryHash } from '@holochain/client';
import { BlockType, AssetInfo, WAL, RenderInfo, BlockName, AppletHash, AppletInfo, AssetLocationAndInfo, OpenAssetMode, CreatableType, CreatableName, Hrl, WeaveLocation, FrameNotification, RecordInfo, PeerStatusUpdate, UnsubscribeFunction, GroupPermissionType, AssetStore } from './types';
declare global {
    interface Window {
        __WEAVE_API__: WeaveServices;
        __WEAVE_APPLET_SERVICES__: AppletServices;
        __WEAVE_RENDER_INFO__: RenderInfo;
        __WEAVE_PROTOCOL_VERSION__: string;
        __MOSS_VERSION__: string;
    }
}
/**
 * The null hash is used in case a WAL is to address a DNA only, not specific
 * DHT content. It starts with the prefix of an EntryHash, followed by zeroes
 */
export declare const NULL_HASH: Uint8Array<ArrayBuffer>;
/**
 *
 * @returns bool: Returns whether this function is being called in a Weave context.
 */
export declare const isWeaveContext: () => true;
/**
 *
 * @param appletHash Hash of the applet to generate the link for
 * @param webPrefix Whether to make the link work via web browsers. Default is true.
 * @returns
 */
export declare const weaveUrlFromAppletHash: (appletHash: AppletHash, webPrefix?: boolean) => string;
export declare function weaveUrlFromWal(wal: WAL, webPrefix?: boolean): string;
export declare function weaveUrlToLocation(url: string): WeaveLocation;
export declare function weaveUrlToWAL(url: string): WAL;
export declare function stringifyHrl(hrl: Hrl): string;
export declare function stringifyWal(wal: WAL): string;
export declare function deStringifyWal(walStringified: string): WAL;
export declare function encodeContext(context: any): string;
export declare function decodeContext(contextStringified: string): any;
export declare const initializeHotReload: () => Promise<void>;
export declare class AppletServices {
    constructor();
    /**
     * Creatables that this Applet offers to be created from a We dialog
     */
    creatables: Record<CreatableName, CreatableType>;
    /**
     * Render block types that this Applet offers
     */
    blockTypes: Record<BlockName, BlockType>;
    /**
     * Get info about the specified entry of this Applet
     */
    getAssetInfo: (appletClient: AppClient, wal: WAL, recordInfo?: RecordInfo) => Promise<AssetInfo | undefined>;
    /**
     * Search in this Applet
     */
    search: (appletClient: AppClient, appletHash: AppletHash, weaveServices: WeaveServices, searchFilter: string) => Promise<Array<WAL>>;
}
export interface AssetServices {
    /**
     * Gets information about an entry in any other Applet in We
     * @param wal
     * @returns
     */
    assetInfo: (wal: WAL) => Promise<AssetLocationAndInfo | undefined>;
    /**
     * Communicate that an asset is being dragged
     * @param wal
     * @param context
     * @returns
     */
    dragAsset: (wal: WAL) => Promise<void>;
    /**
     * Adds the specified HRL to the We-internal clipboard
     * @param wal
     * @returns
     */
    assetToPocket: (wal: WAL) => Promise<void>;
    /**
     * Prompts the user to select an Asset and returns the associated WAL as soon
     * as the user has selected an asset or returns undefined if the user cancels
     * the selection process.
     * By default it will let the user select the Asset from the pocket but other
     * means of selecting the asset can be specified optionally with the "from"
     * argument.
     *
     * @param from (optional) source of the WAL
     * @returns
     */
    userSelectAsset: (from?: 'search' | 'pocket' | 'create') => Promise<WAL | undefined>;
    /**
     * Prompts the user with a dialog to select an asset relation tag.
     * Returns the associated tag as a string as soon as the user has
     * selected a tag or undefined it the user cancels the selection
     * process.
     *
     * @returns
     */
    userSelectAssetRelationTag: () => Promise<string | undefined>;
    /**
     * Adds new tags to an asset
     *
     * @param wal
     * @param tags
     * @returns
     */
    addTagsToAsset: (wal: WAL, tags: string[]) => Promise<void>;
    /**
     * Removes the given tags from an asset.
     *
     * @param wal
     * @param tags
     * @returns
     */
    removeTagsFromAsset: (wal: WAL, tags: string[]) => Promise<void>;
    /**
     * Adds a new asset relation. This function deliberately returns no value because
     * Tool frontends should subscribe to the AssetStore(s) to update their frontend
     * state.
     *
     * @param srcWal
     * @param dstWal
     * @param tags
     * @returns
     */
    addAssetRelation: (srcWal: WAL, dstWal: WAL, tags?: string[]) => Promise<void>;
    /**
     * Removes an asset relation and all its tags. This function deliberately returns
     * no value because Tool frontends should subscribe to the AssetStore(s) to update
     * their frontend state.
     *
     * @param relationHash
     * @returns
     */
    removeAssetRelation: (relationHash: EntryHash) => Promise<void>;
    /**
     * Adds new tags to an existing asset relation
     *
     * @param relationHash
     * @param tags
     * @returns
     */
    addTagsToAssetRelation: (relationHash: EntryHash, tags: string[]) => Promise<void>;
    /**
     * Removes the specified tags from an asset relation
     *
     * @param relationHash
     * @param tags
     * @returns
     */
    removeTagsFromAssetRelation: (relationHash: EntryHash, tags: string[]) => Promise<void>;
    /**
     * Get all asset relation tags that have been used so far in the group. Useful for
     * example to display in a tag selection UI element.
     *
     * @param crossGroup Whether to get all tags across all groups. By default false.
     * @returns
     */
    getAllAssetRelationTags: (crossGroup?: boolean) => Promise<string[]>;
    /**
     * Returns a Svelte readable store that can be subscribed to in order to get updated
     * about the latest information about this asset (tags and other related assets)
     *
     * @param wal
     * @returns
     */
    assetStore: (wal: WAL) => AssetStore;
}
export interface WeaveServices {
    assets: AssetServices;
    /**
     *
     * @returns Version of Moss within which this method is being called in
     */
    mossVersion: () => string;
    /**
     * Event handler for peer status updates.
     *
     * @param callback Callback that gets called if a peer status update event is emitted
     * @returns
     */
    onPeerStatusUpdate: (callback: (payload: PeerStatusUpdate) => any) => UnsubscribeFunction;
    /**
     * Event listener allowing to register a callback that will get executed before the
     * applet gets reloaded, for example to save intermediate user input (e.g. commit
     * the most recent changes of a document to the source chain).
     *
     * If this callback takes too long, users may be offered to force reload, thereby
     * ignoring/cancelling the pending callback.
     *
     * @param callback Callback that gets called before the Applet gets reloaded
     * @returns
     */
    onBeforeUnload: (callback: () => void) => UnsubscribeFunction;
    /**
     * Open the main view of the specified Applet
     * @param appletHash
     * @returns
     */
    openAppletMain: (appletHash: EntryHash) => Promise<void>;
    /**
     * Open the specified block view of the specified Applet
     * @param appletHash
     * @param block
     * @param context
     * @returns
     */
    openAppletBlock: (appletHash: any, block: string, context: any) => Promise<void>;
    /**
     * Open the cross-applet main view of the specified Applet Type.
     * @param appletBundleId
     * @returns
     */
    openCrossGroupMain: (appletBundleId: string) => Promise<void>;
    /**
     * Open the specified block view of the specified Applet Type
     * @param appletBundleId
     * @param block
     * @param context
     * @returns
     */
    openCrossGroupBlock: (appletBundleId: string, block: string, context: any) => Promise<void>;
    /**
     * Open the asset associated to the specified WAL
     * @param wal
     * @param context
     * @returns
     */
    openAsset: (wal: WAL, mode?: OpenAssetMode) => Promise<void>;
    /**
     * Get the group profile of the specified group
     * @param groupHash
     * @returns
     */
    groupProfile: (groupHash: any) => Promise<any>;
    /**
     * Returns Applet info of the specified Applet
     * @param appletHash
     * @returns
     */
    appletInfo: (appletHash: any) => Promise<AppletInfo | undefined>;
    /**
     * Sends notifications to We and depending on user settings and urgency level
     * further to the operating system.
     * @param notifications
     * @returns
     */
    notifyFrame: (notifications: Array<FrameNotification>) => Promise<any>;
    /**
     * Let's the user select a Screen or Window and returns the selected id. Useful
     * for screen sharing applications.
     */
    userSelectScreen: () => Promise<string>;
    /**
     * Requests to close the containing window. Will only work if the applet is being run in its
     * own window
     */
    requestClose: () => Promise<void>;
    /**
     * Gets the group permission type. May be used to restrict certain actions in the UI.
     * @returns
     */
    myGroupPermissionType: () => Promise<GroupPermissionType>;
    /**
     * Gets all the agents that joined the Tool instance of the Tool calling this function
     * @returns
     */
    appletParticipants: () => Promise<AgentPubKey[]>;
    /**
     * Allows to send small sized "fire-and-forget" signals to all group participants
     * that are currently online.
     *
     * @param payload Arbitrary payload, for example any msgpack encoded javascript object
     * @returns
     */
    sendRemoteSignal: (payload: Uint8Array) => Promise<void>;
    /**
     * Event listener allowing to register a callback that will get executed if a remote
     * signal that had been sent with `WeaveClient.sendRemoteSignal()` arrives.
     *
     * @param callback
     * @returns
     */
    onRemoteSignal: (callback: (payload: Uint8Array) => any) => UnsubscribeFunction;
    /**
     * Create a cloned cell and optionally have it be registered in the group DNA for other
     * group members or always-online nodes to be able to automatically join it too.
     *
     * @param req
     * @param publicToGroupMembers Whether this cloned cell should be registered in the group DNA such that
     * other group members or alway-online nodes may automatically install it too.
     * @returns
     */
    createCloneCell: (req: CreateCloneCellRequest, publicToGroupMembers: boolean) => Promise<CreateCloneCellResponse>;
    enableCloneCell: (req: EnableCloneCellRequest) => Promise<CreateCloneCellResponse>;
    disableCloneCell: (req: DisableCloneCellRequest) => Promise<void>;
}
export declare class WeaveClient implements WeaveServices {
    get renderInfo(): RenderInfo;
    private constructor();
    static connect(appletServices?: AppletServices): Promise<WeaveClient>;
    mossVersion: () => string;
    onPeerStatusUpdate: (callback: (payload: PeerStatusUpdate) => any) => UnsubscribeFunction;
    onBeforeUnload: (callback: () => any) => UnsubscribeFunction;
    openAppletMain: (appletHash: EntryHash) => Promise<void>;
    openAppletBlock: (appletHash: any, block: string, context: any) => Promise<void>;
    openCrossGroupMain: (appletBundleId: string) => Promise<void>;
    openCrossGroupBlock: (appletBundleId: string, block: string, context: any) => Promise<void>;
    openAsset: (wal: WAL, mode?: OpenAssetMode) => Promise<void>;
    assets: AssetServices;
    groupProfile: (groupHash: any) => Promise<any>;
    appletInfo: (appletHash: any) => Promise<AppletInfo | undefined>;
    notifyFrame: (notifications: Array<FrameNotification>) => Promise<any>;
    userSelectScreen: () => Promise<string>;
    requestClose: () => Promise<void>;
    myGroupPermissionType: () => Promise<GroupPermissionType>;
    appletParticipants: () => Promise<import("@holochain/client").HoloHash[]>;
    sendRemoteSignal: (payload: Uint8Array) => Promise<void>;
    onRemoteSignal: (callback: (payload: Uint8Array) => any) => UnsubscribeFunction;
    createCloneCell: (req: CreateCloneCellRequest, publicToGroupMembers: boolean) => Promise<import("@holochain/client").ClonedCell>;
    enableCloneCell: (req: EnableCloneCellRequest) => Promise<import("@holochain/client").ClonedCell>;
    disableCloneCell: (req: DisableCloneCellRequest) => Promise<void>;
}