@vivoa/plugin-sdk

Public contracts for Vivoa plugins. Pure TypeScript types, DI tokens, and runtime validators. No host coupling, no React, no framework imports.

A plugin author depends on this package; the Vivoa host re-exports it as its single source of truth for plugin shapes.

Install

npm install @vivoa/plugin-sdk

What's inside

| Module | Exports | | ---------------- | ----------------------------------------------------------------------- | | types | IPlugin, IPaymentPlugin, IShippingPlugin, payment/shipping models, DI tokens | | manifest | PluginManifest | | config-schema | createPluginConfig, field — declarative config + superstruct validation | | setup-layout | SetupLayout types, validateSetupLayout, crossValidateSetupLayout |

All exported from the package root:

import {
  IPaymentPlugin,
  createPluginConfig,
  field,
  validateSetupLayout,
} from '@vivoa/plugin-sdk';

Defining a configurable plugin

import { createPluginConfig, field } from '@vivoa/plugin-sdk';

const config = createPluginConfig({
  apiKey: field({ label: 'API Key', type: 'password' }),
  sandbox: field({ label: 'Sandbox', type: 'boolean', required: false }),
});

config.configFields; // -> PluginConfigField[] for the admin UI
config.validate(input); // -> { success, data | errors }

Validating a setup layout

import { validateSetupLayout, crossValidateSetupLayout } from '@vivoa/plugin-sdk';

const res = validateSetupLayout(manifest.setup);
if (!res.success) throw new Error(res.errors.join('\n'));

const keyErrors = crossValidateSetupLayout(res.data, config.configFields);

Versioning

Semver. Breaking changes to any exported type or validator bump the major. Plugins should pin a caret range (^0.1.0).

License

MIT