diff --git a/docs/dev_tools/agent_explorer_plugin.md b/docs/dev_tools/agent_explorer_plugin.md new file mode 100644 index 0000000..2157a16 --- /dev/null +++ b/docs/dev_tools/agent_explorer_plugin.md @@ -0,0 +1,327 @@ +--- +id: agent_explorer_plugin +title: Agent Explorer Plugin +--- + +`@veramo-community/agent-explorer-plugin` package defines the common interface for an agent explorer plugin. + +## Usage + +Plugins have an init function that returns a configuration object. +The configuration object defines locations in the `agent-explore` UI that will get modified by the plugin as well as +some of the methods it will use from the associated Veramo agent. + +### Example + +A [plugin](https://github.com/veramolabs/agent-explorer/blob/main/packages/agent-explore/src/plugins/contacts/index.tsx#L9) that adds a new menu item and a new page to the UI to manage some contacts. + +```tsx +import { IPlugin } from '@veramo-community/agent-explorer-plugin'; + +const Plugin: IPlugin = { + init: () => { + return { + config: { + enabled: true, + url: 'core://contacts', + }, + name: 'Contacts', + description: 'Explore contacts', + icon: , + requiredMethods: ['dataStoreORMGetIdentifiers'], + routes: [ + { + path: '/contacts', + element: , + }, + { + path: '/contacts/:id', + element: , + }, + ], + menuItems: [ + { + name: 'Contacts', + path: '/contacts', + icon: , + }, + ], + getCredentialContextMenuItems + } + } +}; + +``` + +### Example implementations + +- [veramolabs/agent-explorer-plugin-brainshare](https://github.com/veramolabs/agent-explorer-plugin-brainshare) +- [veramolabs/agent-explorer-plugin-gitcoin-passport](https://github.com/veramolabs/agent-explorer-plugin-gitcoin-passport) +- [veramolabs/agent-explorer-plugin-kudos](https://github.com/veramolabs/agent-explorer-plugin-kudos) +- [veramolabs/agent-explorer-plugin-graph-view](https://github.com/veramolabs/agent-explorer-plugin-graph-view) +- [veramolabs/agent-explorer-plugin-social-feed](https://github.com/veramolabs/agent-explorer-plugin-social-feed) +- [veramolabs/agent-explorer-plugin-developer-tools](https://github.com/veramolabs/agent-explorer-plugin-developer-tools) +- [simonas-notcat/agent-explorer-plugin-codyfight](https://github.com/simonas-notcat/agent-explorer-plugin-codyfight) + +All of these plugins use the same project structure. + +You can use any of them as a template for your own plugin. + +### Local development + +#### Option1: with `ngrok` + +- Clone any of the above mentioned plugin repositories +- Run `pnpm i` +- Run `pnpm serve` to start the development server +- Run `pnpm ngrok` to open a tunnel to your local server +- Copy the ngrok url and paste it in the text field after clicking Add in https://explore.veramo.io/settings/plugins + +``` +https://EXAMPLE.ngrok.app/plugin.js +``` + +https://github.com/veramolabs/agent-explorer/assets/16773277/0fda3289-1d71-4559-97d4-786069e3a334 + +#### Option 2: without `ngrok` + +Run local `agent-explore` instance + +```bash +git clone https://github.com/veramolabs/agent-explorer.git +cd agent-explorer +pnpm i +cd packages/plugin +pnpm build +cd ../agent-explore +pnpm dev +``` + + +- Clone any of the above mentioned plugin repositories +- Run `pnpm i` +- Run `pnpm serve` to start the development server +- Copy `http://localhost:8080/plugin.js` and paste it in the text field after clicking Add http://localhost:3000/plugins + + +### Publishing + +- Run `pnpm build` +- Commit changes and push to github +- Use the github url to load the plugin in `agent-explore` + +``` +https://cdn.jsdelivr.net/gh/{USER}/{REPO}/dist/plugin.js +``` +## Plugin API + +### `name` + +The plugin name + +```ts +name: string; +``` + +### `description` + +A short description of the plugin + +```ts +description: string; +``` + +### `icon` + +The plugin icon +```ts +icon?: React.ReactNode; +``` + +These will be displayed in the plugins list + +![plugin-list](./plugin-list.png) + +### `routes` + +```ts +/** An array of routes to be added to the explorer */ +routes?: IRouteComponent[]; +``` +Example: +```ts +routes: [ + { + path: '/contacts', + element: , + }, + { + path: '/contacts/:id', + element: , + }, +] +``` + +### `menuItems` + +An array of menu items to be added to the explorer + +```ts +menuItems?: ExtendedMenuDataItem[]; +``` + +Example: +```ts +menuItems: [ + { + name: 'Contacts', + path: '/contacts', + icon: , + }, +], +``` + +![contacts](./contacts.png) + +### `requiredMethods` + +An array of methods that the plugin requires to be implemented by the agent. + +If the agent does not implement the required methods, the plugin will be loaded but the menu item will not be shown. +```ts +requiredMethods: string[]; +``` + +Example: +```ts +requiredMethods: ['dataStoreORMGetIdentifiers'], +``` + + + +### `hasCss` + +Does the plugin provide custom css + +```ts +hasCss?: boolean; +``` + +Example: [Brainshare](https://github.com/veramolabs/agent-explorer-plugin-graph-view/tree/main/dist) plugin provides custom css. + +### `agentPlugins` + +Veramo agent plugins accesable by all explorer plugins + +```ts +agentPlugins?: IAgentPlugin[]; +``` + +### `messageHandlers` + +Veramo agent message handlers + +```ts +messageHandlers?: AbstractMessageHandler[]; +``` + +Example: [Chats plugin](https://github.com/veramolabs/agent-explorer/blob/main/packages/agent-explore/src/plugins/chats/index.tsx#L20) + +### `getCredentialContextMenuItems` + +Menu items for the credential context menu + +```ts +getCredentialContextMenuItems?: (credential: UniqueVerifiableCredential) => MenuProps['items']; +``` + +Example [Chats plugin](https://github.com/veramolabs/agent-explorer/blob/7614ba2a25423aa6304013738af8e67c625394cd/packages/agent-explore/src/plugins/chats/menu.tsx#L8) + +```ts +{ + key: 'sendto', + label: 'Share with ...', + icon: , + onClick: handleSendTo +} +``` + +![Credential context menu](./credential-context-menu.png) + +### `getCredentialComponent` + +Returns a react component for a given verifiable credential + +```ts +getCredentialComponent?: (credential: UniqueVerifiableCredential) => React.FC | undefined; +``` + +Example: [Kudos plugin](https://github.com/veramolabs/agent-explorer-plugin-kudos/blob/e2535b295ef91c6c85d3530313ec5ed5c5aefb4c/src/index.tsx#L32) + +![Kudos credential](./kudos.png) + +### `getIdentifierHoverComponent` + +Returns a react component that will be displayed in the identifier hover component + +```ts +getIdentifierHoverComponent?: () => React.FC; +``` +Example: [Gitcoin Passport plugin](https://github.com/veramolabs/agent-explorer-plugin-gitcoin-passport/blob/main/src/index.tsx#L20) + +![Identifier hover](./identifier-hover.png) + +### `getIdentifierTabsComponents` + +Returns an array of react components and labels that will be displayed as tabs in the indentifier profile page + +```ts +getIdentifierTabsComponents?: () => Array<{ label: string, component: React.FC }>; +``` + +Example: [Credentials plugin](https://github.com/veramolabs/agent-explorer/blob/42c625bdcfe03c725abb2cf3db88bec2e3e90a99/packages/agent-explore/src/plugins/credentials/index.tsx) + +```ts +getIdentifierTabsComponents: () => { + return [ + { + label: 'Issued credentials', + component: IdentifierIssuedCredentials, + }, + { + label: 'Received credentials', + component: IdentifierReceivedCredentials, + }, + ] +} +``` +![Identifier tabs](./identifier-tabs.png) + +### `getCredentialActionComponents` + +Returns an array of react components that will be displayed as action buttons in Credential component + +```ts +getCredentialActionComponents?: () => Array>; +``` + +Example: [Reactions plugin](https://github.com/veramolabs/agent-explorer/blob/main/packages/agent-explore/src/plugins/reactions/index.tsx#L33) + +![Credential actions](./reactions.png) + +### `getMarkdownComponents` + +`react-markdown` Components for custom markdown rendering + +```ts +getMarkdownComponents?: () => Partial | undefined; +``` +### `getRemarkPlugins` + +`remark` plugins for custom markdown manipulations + +```ts +getRemarkPlugins?: () => PluggableList; +``` + +Example: [Brainshare plugin](https://github.com/veramolabs/agent-explorer-plugin-brainshare/blob/4de0d677ffd907dcbaf59028647e45967fdd9c85/src/index.tsx#L105) \ No newline at end of file diff --git a/docs/dev_tools/contacts.png b/docs/dev_tools/contacts.png new file mode 100644 index 0000000..c0ac69d Binary files /dev/null and b/docs/dev_tools/contacts.png differ diff --git a/docs/dev_tools/credential-context-menu.png b/docs/dev_tools/credential-context-menu.png new file mode 100644 index 0000000..425f5e4 Binary files /dev/null and b/docs/dev_tools/credential-context-menu.png differ diff --git a/docs/dev_tools/identifier-hover.png b/docs/dev_tools/identifier-hover.png new file mode 100644 index 0000000..30cf25f Binary files /dev/null and b/docs/dev_tools/identifier-hover.png differ diff --git a/docs/dev_tools/identifier-tabs.png b/docs/dev_tools/identifier-tabs.png new file mode 100644 index 0000000..99b168d Binary files /dev/null and b/docs/dev_tools/identifier-tabs.png differ diff --git a/docs/dev_tools/kudos.png b/docs/dev_tools/kudos.png new file mode 100644 index 0000000..0354a9f Binary files /dev/null and b/docs/dev_tools/kudos.png differ diff --git a/docs/dev_tools/plugin-list.png b/docs/dev_tools/plugin-list.png new file mode 100644 index 0000000..8e65ad5 Binary files /dev/null and b/docs/dev_tools/plugin-list.png differ diff --git a/docs/dev_tools/reactions.png b/docs/dev_tools/reactions.png new file mode 100644 index 0000000..f3cc50d Binary files /dev/null and b/docs/dev_tools/reactions.png differ diff --git a/sidebars.js b/sidebars.js index ced6303..1d97f8b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -31,6 +31,7 @@ module.exports = { 'dev_tools/veramo_cli', 'dev_tools/veramo_react', 'dev_tools/agent_explorer', + 'dev_tools/agent_explorer_plugin', // 'dev_tools/ssi_toolkit', // 'dev_tools/nft_toolkit', // 'dev_tools/web3_toolkit',