CI Shared

Repositories Projects Packages

41

@adverant-nexus/plugin-sdk (1.0.0)

Published 2026-07-30 15:58:41 +00:00 by forgejo_admin

Installation

Setup this registry in your project .npmrc file:

@adverant-nexus:registry=

To install the package using npm, run the following command:

npm install @adverant-nexus/plugin-sdk@1.0.0

or add it to the package.json file:

"@adverant-nexus/plugin-sdk": "1.0.0"

For more information on the npm registry, see the documentation.

About this package

@adverant-nexus/plugin-sdk

The canonical SDK for building sovereign, white-labeled Nexus marketplace plugins.

A Nexus plugin is an independent tenant of the Adverant control plane: its own repo, its own domain, its own pods, its own brand — and a customer using it must never see Adverant. This SDK is the contract that makes that possible and safe:

• One versioned manifest schema (nexus.manifest v1) — replaces the four incompatible manifest shapes that grew up across the platform.
• definePlugin / defineSkill — validate a manifest against the schema and the semantic invariants JSON-Schema can't express, then freeze it. No silent coercion; a manifest that survives is one the onboarding pipeline can register without re-checking.
• Trust tiers + isolation posture — declarative metadata the control-plane gates read; the SDK never bypasses a gate.
• NexusAppBridge — a typed, origin-checked postMessage client for a plugin's frontend surface.
• compileRegistry — turn a manifest's declared skills into the POST /api/v1/plugins/sync payload, so skills reach the registry automatically instead of via hand-written SQL.
• create-nexus-plugin — a pure-node CLI (no network, no remote import) to scaffold and validate.

See the runnable reference plugin: nexus-plugin-demo.

Install

npm install @adverant-nexus/plugin-sdk

Author a manifest

import { definePlugin } from "@adverant-nexus/plugin-sdk";

export default definePlugin({
  manifestVersion: "1",
  name: "acme-insights",
  displayName: "Acme Insights",
  version: "1.0.0",
  description: "Lead scoring and account intelligence.",
  author: "Acme Inc",
  license: "MIT",
  tier: "full-service",          // skills-only | ui-only | full-service
  trust: "community",            // core | verified | community | untrusted
  runtime: { executionMode: "hardened_docker", isolationLevel: 3, entrypoint: "dist/index.js" },
  backend: { port: 8080, healthPath: "/health", apiPrefix: "/api" },
  frontend: { basePath: "/app", framework: "next" },
  domain: { primary: "acme.example.com" },
  branding: { appName: "Acme Insights", passkeyRpId: "acme.example.com" },
  databases: [{ engine: "postgresql", schema: "acme_insights", migrations: "database/migrations/" }],
  skills: [
    {
      id: "lead_score",
      displayName: "Lead score",
      description: "Score a lead 0-100.",
      tier: "host_callback",      // host_callback | plugin_queue | tool_using
      classification: "tenant",   // public | tenant | restricted
      inputSchema: { type: "object", properties: { leadId: { type: "string" } }, required: ["leadId"] },
      outputSchema: { type: "object", properties: { score: { type: "number" } }, required: ["score"] },
      hostCallback: { endpoint: "/internal/skills/lead_score" },
    },
  ],
  marketplace: { category: "sales" },
});

definePlugin throws PluginManifestError with a precise path on anything invalid.

Invariants the SDK enforces (beyond the schema)

• LLM egress stays with the platform. tool_using (the only skill tier that reaches the shared AI-Provider Router) is permitted only for trust: core | verified. Community/untrusted plugins may only broker host_callback / plugin_queue skills.
• No cross-origin escape. frontend.basePath and every host_callback.endpoint must be a relative same-origin path — no absolute URL, no scheme, no //host, no backslash (which the URL parser folds to /).
• Classification ceiling. A skill's classification may not exceed its plugin's trust ceiling (untrusted→public, community→tenant, verified/core→restricted).
• MCP safety. An MCP tool's inputSchema may not use a top-level oneOf/allOf/anyOf (it 400s every MCP subagent).
• No remote code. The SDK has no dynamic-import / remote-load path. Trust is authored, verified, and frozen — never fetched.

CLI

# Scaffold a new plugin repo
npx create-nexus-plugin scaffold my-plugin --tier full-service

# Validate a manifest (exit 0 = valid, 1 = invalid)
npx create-nexus-plugin validate nexus.manifest.json

Develop

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run build       # emit dist/

License

MIT © Adverant

Dependencies

Dependencies

ID	Version
ajv	^8.17.1
ajv-formats	^3.0.1

Development dependencies

ID	Version
@types/node	^20.14.0
tsx	^4.16.0
typescript	^5.5.4
vitest	^2.0.5

Keywords

nexus adverant plugin sdk marketplace white-label multi-tenant

Details

npm

2026-07-30 15:58:41 +00:00

5

MIT

latest

21 KiB

Assets (1)

plugin-sdk-1.0.0.tgz 21 KiB

Versions (1) View all

1.0.0 2026-07-30