donmai — the OSS workflow runtime

A donmai plugin is a package that exports a default object implementing the IPlugin interface. donmai discovers and loads it at startup based on config declarations.

`IPlugin` interface

export interface IPlugin {
  /** Unique identifier for this plugin, e.g. "@donmai/plugin-linear" */
  name: string;

  /** Semver version string */
  version: string;

  /**
   * Called once when the plugin is loaded.
   * Register node types, credential schemas, and trigger sources here.
   */
  register(ctx: PluginContext): void | Promise<void>;

  /**
   * Called when the daemon is shutting down.
   * Clean up connections, flush buffers, etc.
   */
  shutdown?(): void | Promise<void>;
}

`PluginContext`

register(ctx) receives a PluginContext with the following methods:

export interface PluginContext {
  /** Register a new workflow node type */
  registerNode(definition: NodeDefinition): void;

  /** Register a credential schema for OAuth or API key auth */
  registerCredentialType(schema: CredentialSchema): void;

  /** Register a trigger source (webhook, polling, etc.) */
  registerTrigger(trigger: TriggerDefinition): void;
}

Lifecycle hooks

Plugins can hook into the workflow execution lifecycle by implementing optional methods:

Method	When it fires
`beforeWorkflow(ctx)`	Before a workflow starts executing
`afterWorkflow(ctx)`	After a workflow completes (success or failure)
`beforeStep(ctx)`	Before each step executes
`afterStep(ctx)`	After each step completes
`onError(ctx, err)`	When a step or workflow throws an unhandled error

Minimal example

// index.ts
import type { IPlugin, PluginContext } from 'donmai';

const plugin: IPlugin = {
  name: '@example/plugin-hello',
  version: '0.1.0',

  register(ctx: PluginContext) {
    ctx.registerNode({
      type: 'hello.greet',
      label: 'Greet',
      description: 'Prints a greeting message.',
      inputs: [
        { name: 'name', type: 'string', required: true },
      ],
      outputs: [
        { name: 'message', type: 'string' },
      ],
      async execute({ inputs }) {
        return { message: `hello, ${inputs.name}` };
      },
    });
  },
};

export default plugin;

Publishing

Plugins intended for the broader donmai ecosystem should be published under the @donmai/* npm scope. To request scope access, open an issue in the donmai repository.

For private or internal plugins, any npm package name works — just ensure it is resolvable from the environment where donmai runs.

Types package

Import types from the donmai package:

npm install --save-dev donmai

The types package is available at v0.9.0 and later.

IPlugin interface