@vivoa/plugin-sdk 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vivoa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @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.
+
+> **Building a plugin?** Read [`AUTHORING.md`](./AUTHORING.md) — the complete,
+> AI-legible guide (anatomy, `IPaymentPlugin`/`IShippingPlugin`, config, setup
+> layout, permissions, build/publish, and the host landmines to avoid).
+
+## Install
+
+```bash
+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:
+
+```ts
+import {
+  IPaymentPlugin,
+  createPluginConfig,
+  field,
+  validateSetupLayout,
+} from '@vivoa/plugin-sdk';
+```
+
+## Defining a configurable plugin
+
+```ts
+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
+
+```ts
+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