@giduru/plugin-api

Public TypeScript contracts for Giduru plugins.

This package intentionally exposes only the plugin-facing surface: manifest types, install config types, theme contributions, command contributions, view registration, and the browser host API available as window.giduru.

Install

npm install --save-dev @giduru/plugin-api

Manifest

import { defineGiduruPluginManifest } from '@giduru/plugin-api';

export default defineGiduruPluginManifest({
  id: 'dev.giduru.demo',
  name: 'Giduru Demo Plugin',
  version: '0.1.0',
  giduruApiVersion: 1,
  permissions: ['ledger.read', 'navigation.openView'],
  platforms: ['web', 'ios', 'android'],
  contributes: {
    views: [
      {
        path: 'giduru-plugin://dev.giduru.demo/view/overview',
        label: 'Demo Overview',
        viewPath: 'Plugins/Demo/Overview',
        entry: 'view.js',
      },
    ],
    commands: [
      {
        id: 'open-overview',
        title: 'Open Demo Plugin Overview',
        category: 'Plugins',
        action: {
          type: 'open-view',
          path: 'giduru-plugin://dev.giduru.demo/view/overview',
        },
      },
    ],
    themes: [
      {
        id: 'demo-dark',
        label: 'Demo Dark',
        kind: 'dark',
        colors: {
          border: '#293241',
          borderStrong: '#3d5a80',
          editor: '#0b1020',
          foreground: '#eef2ff',
          foregroundMuted: '#a8b3cf',
          green: '#72efdd',
          panel: '#111827',
          panelAlt: '#182235',
          panelSoft: '#1f2a44',
          primary: '#98c1d9',
          primaryText: '#08111f',
          red: '#ee6c4d',
          redSoft: '#3d1f22',
          slate: '#7b879f',
          warning: '#ffd166',
        },
      },
    ],
  },
});

View Entry

import type { GiduruPluginViewContext } from '@giduru/plugin-api';

window.giduru?.registerView({
  path: 'giduru-plugin://dev.giduru.demo/view/overview',
  render(container: HTMLElement, context: GiduruPluginViewContext) {
    let latestSnapshot = context.snapshot;

    function paint() {
      container.textContent = `Vault: ${latestSnapshot.vault?.name ?? 'None'}`;
    }

    paint();
    return context.subscribe((snapshot) => {
      latestSnapshot = snapshot;
      paint();
    });
  },
});

Vault Config

External plugins are listed in .giduru/plugins.json:

{
  "plugins": [
    {
      "id": "dev.giduru.demo",
      "name": "Giduru Demo Plugin",
      "path": "dev.giduru.demo",
      "manifestUrl": "http://localhost:4173/giduru-plugin.json",
      "version": "0.1.0"
    }
  ]
}

Giduru installs missing remote plugins into .giduru/plugins/<id>/ and then loads the installed manifest and entry files from the vault. During local development, you can edit files directly in .giduru/plugins/<id>/ and omit manifestUrl.