Plugin SDK

This guide is the public starting point for building a NashTwin plugin. Use it to understand what to ship, how to shape your manifest.json, how the submission flow works in the Developer Portal, and which supporting docs you should read before asking for Marketplace publication.

For the strict field-by-field rules, see the Plugin Contract. For UI work inside the product shell, see Plugin UI Best Practices.

Quickstart

1. Create a developer account at developers.gatewaycorporate.org.
2. Model your plugin around a single manifest.json file.
3. Implement only the capabilities and events your plugin actually needs.
4. Validate the manifest locally before submission.
5. Submit the manifest through the Developer Portal.
6. Address any review notes, then publish once the submission is approved.

What You Ship

Every plugin centers on one file: manifest.json.

Most production plugins also include runtime code, tests, and optionally UI assets.

Typical layout:

your-plugin/
	manifest.json
	package.json
	src/
		index.ts
		webhook.ts
		ui/
			panel.tsx
	README.md

What each part does

• manifest.json defines the plugin contract that NashTwin validates and stores.
• package.json tracks runtime and build dependencies.
• src/index.ts contains your main runtime behavior.
• src/webhook.ts handles server-triggered delivery if your integration has an approved external transport.
• src/ui/* holds UI surfaces rendered inside NashTwin when your plugin exposes in-product interfaces.
• README.md is for your team; the Marketplace and review pipeline rely on the manifest and any separate support docs.

The Manifest

The manifest is the only required file. It describes identity, capabilities, event subscriptions, configuration, optional graph participation, optional optimization participation, and Marketplace metadata.

Example:

{
	"id": "com.yourcompany.pipeline-optimizer",
	"name": "Pipeline Optimizer",
	"description": "Ranks pipeline actions and surfaces decision support inside NashTwin.",
	"version": "1.2.0",
	"author": "Your Company",
	"authorUrl": "https://yourcompany.com",
	"iconUrl": "https://yourcompany.com/logo.png",
	"capabilities": ["game-theory-strategy", "ui-component"],
	"events": ["deal.created", "deal.updated", "simulation.requested"],
	"configSchema": {
		"type": "object",
		"properties": {
			"approvalWorkflowEnabled": { "type": "boolean", "description": "Require human approval before operationalizing a move." },
			"simulationQuotaLimit": { "type": "number", "minimum": 1, "description": "Maximum launches inside the configured quota window." }
		}
	},
	"graphExtension": {
		"contributions": [
			{
				"kind": "node",
				"schemaId": "com.yourcompany.graph.pipeline-recommendation",
				"displayName": "Pipeline Recommendation",
				"description": "Derived move recommendations attached to a deal or pipeline context.",
				"layer": "derived-overlay",
				"nodeFamily": "process",
				"version": "1.0.0",
				"dataClassificationTargets": ["INTERNAL", "CONFIDENTIAL"]
			}
		],
		"handledDataClassifications": ["INTERNAL", "CONFIDENTIAL"],
		"readScopes": ["graph.read.governed-core", "graph.read.derived-overlay"],
		"residencyGuarantees": ["US"],
		"retentionStrategy": "PLATFORM_POLICY",
		"supportedEventSchemaVersions": ["1.0.0"],
		"writeScopes": ["graph.write.derived-overlay"]
	},
	"optimizationExtension": {
		"advisoryOnly": true,
		"defaultRuntimeMode": "inline",
		"defaultRecommendationCount": 3,
		"maxHorizon": 12,
		"maxRecommendationCount": 5,
		"requiresHumanReview": true,
		"supportsApprovalWorkflow": true,
		"supportsExternalWorkers": false,
		"supportsOutcomeCapture": true,
		"supportedGameClasses": ["normal-form-strategic", "repeated-dynamic"],
		"supportedSolverFamilies": ["nash-equilibrium", "adversarial-simulation"],
		"supportedTimeScales": ["weekly", "monthly", "quarterly"],
		"supportedUtilityTopologies": ["general-sum", "unknown"],
		"timeoutMs": 15000
	},
	"tags": ["optimization", "pipeline", "decision-support"]
}

Capability Overview

NashTwin currently validates five plugin capabilities:

Event Subscriptions

Plugin manifests may subscribe to the public event types listed in the Plugin Contract. The most common patterns in the current codebase are:

• contact.created and contact.updated for enrichment workflows.
• deal.created and deal.updated for CRM-triggered scoring or recommendation workflows.
• twin.updated for graph-backed projections and model refreshes.
• simulation.requested, simulation.completed, simulation.failed, recommendation.generated, and outcome.recorded for optimization workflows.

Not every optimization-related event in the codebase is currently accepted in third-party manifests. Treat the contract document as the publishable subscription surface.

Graph-Aware Plugins

Add graphExtension when your plugin contributes graph records or reads graph-backed twin data. That extension does three things:

1. Declares the schemas your plugin contributes.
2. Declares the graph read and write scopes your runtime needs.
3. Declares the event envelope versions your graph-aware runtime understands.

Practical guidance:

• Keep schemaId values reverse-domain and semver every contribution.
• Keep readScopes and writeScopes narrow.
• Only declare classifications your runtime can actually process safely.
• Treat supportedEventSchemaVersions as a compatibility statement, not filler metadata.

Optimization Plugins

If you declare game-theory-strategy, review whether you also need optimizationExtension.

That extension is how you tell NashTwin:

• which game classes you support
• which solver families you run
• whether the plugin is advisory-only
• whether human review, outcome capture, or worker execution are supported
• which scenarios the tenant can launch through the product UI

The first-party Nash Optimization and SaaS Model plugins are the best reference shapes currently in the repo. The public rules for every field are in the Plugin Contract.

Local Validation

The same validator used by submission review is exported from @nashtwin/common.

Example:

import { validatePluginManifest } from '@nashtwin/common'

import manifest from './manifest.json'

validatePluginManifest(manifest)

Validation catches the main structural issues early:

• invalid reverse-domain IDs
• non-semver versions
• unknown capabilities or event types
• malformed graph contributions
• invalid optimization scenario IDs

Submission and Review Flow

The Developer Portal currently supports a straightforward manifest-first workflow.

Developer flow

1. Sign in to the portal.
2. Paste a complete manifest into the submission form.
3. The portal validates it before creating a submission.
4. If you already have an active submission under review, you must wait for that decision before opening another active review.

Review states

Current states used by the admin flow are:

• PENDING
• UNDER_REVIEW
• REJECTED
• PUBLISHED

When an admin publishes a submission, the manifest is validated again and then upserted into the plugin registry as a third-party plugin.

What reviewers check

• manifest validity
• capability and event alignment
• configuration clarity
• graph scope discipline, if present
• optimization scenario quality, if present
• whether the plugin description, tags, and icon are ready for Marketplace display

UI Work

If your plugin renders in-product UI, do not treat it as a standalone microsite. Existing plugin surfaces in NashTwin are compact, task-focused, and tightly coupled to the surrounding CRM workflow.

Read Plugin UI Best Practices before you implement:

• setup flows
• simulation or analysis panels
• status cards
• configuration forms
• action-heavy operator workflows

Documentation Checklist Before Submission

• manifest validates locally
• descriptions are concise and Marketplace-ready
• config fields have clear descriptions
• tags match the actual capability surface
• graph extension only declares scopes you truly need
• optimization scenarios have stable IDs and human-readable labels
• UI claims match the real surface in your product

Summary

Start with the manifest, validate it locally, and treat the Plugin Contract as the source of truth for publishable behavior. If your plugin includes UI, use the existing NashTwin patterns in Plugin UI Best Practices instead of designing an isolated experience that ignores the host product shell.