The one rule
The core never imports a plugin. Plugins register themselves and contribute to shared surfaces through typed slots. Everything else in this guide follows from that.
Reference
Every bundled plugin is written with exactly this interface. There is no privileged internal API — if we had needed one to build ours, the abstraction would be wrong.
The core never imports a plugin. Plugins register themselves and contribute to shared surfaces through typed slots. Everything else in this guide follows from that.
Core platform
Event bus · Extension points · Tenant isolation · AI gateway
The core never imports a plugin. Remove any of them and the rest keep working.
Never import another plugin
If your plugin needs to know that something happened elsewhere, subscribe to its event. A direct import couples the two permanently and means neither can be removed without breaking the other.
A plugin is one object. Everything beyond identity is optional, so a small plugin stays small.
import { definePlugin } from "@shubham-ai/sdk";
import { Gift } from "lucide-react";
export default definePlugin({
id: "acme.loyalty", // globally unique, <vendor>.<name>
name: "Acme Loyalty",
version: "1.0.0", // semver — validated at registration
category: "crm",
summary: "Points, tiers and rewards.",
description: "Awards points on payment and exposes a balance tool to AI agents.",
icon: Gift,
status: "stable",
dependencies: ["crm.contacts"], // auto-enabled when your plugin is licensed
permissions: ["crm.view", "crm.manage"],
availableTo: ["business"],
pricing: { model: "addon", fromMinor: 39900, unit: "month" },
releasedAt: "2026-07-28",
});That is a valid plugin. It has no interface yet, but it is in the registry, its dependencies are validated, and it appears in the marketplace. Add navigation next.
extensions: [
{
slot: "sidebar.item",
value: {
id: "acme.loyalty.nav",
group: "relationships", // which sidebar section
label: "Loyalty",
path: "/loyalty", // relative to the role's base path
icon: Gift,
permissions: ["crm.view"], // hidden unless the session holds this
},
},
]The entry only renders when the plugin is enabled for the tenant, the role matches, and the session holds the listed permissions. All three, or it does not exist.
Eighteen surfaces you can extend. Each slot is typed, so a widget cannot be registered as a nav item.
| Slot | What it adds |
|---|---|
sidebar.item | A navigation entry in a sidebar group |
dashboard.widget | A card on the role dashboard |
header.action | A button in the application top bar |
table.column | An extra column on a shared table |
table.row_action | A per-row action in a table menu |
table.bulk_action | An action across selected rows |
detail.section | A panel on an entity detail page |
detail.tab | A tab on an entity detail page |
profile.card | A card on a contact or tenant profile |
report.block | A block available in report building |
analytics.metric | A metric the analytics module can chart |
notification.channel | A delivery channel for notifications |
automation.trigger | A trigger for the rules engine |
workflow.node | A node in the flow builder palette |
ai.tool | A capability AI agents can call |
settings.section | A section in tenant settings |
command.palette | An action in the command palette |
onboarding.step | A step in the onboarding checklist |
Declare what you emit so the marketplace can show your contract, and subscribe to what you care about. Handlers are typed per event name.
emits: ["loyalty.points_awarded"],
subscribes: {
// Typed per event name — payload is inferred.
"payment.completed": async (event) => {
const { paymentId, amountMinor } = event.payload;
// meta.tenantId is always present. You cannot forget to scope.
await award(event.meta.tenantId, paymentId, Math.floor(amountMinor / 100));
},
"deal.won": async (event) => {
await awardBonus(event.meta.tenantId, event.payload.leadId);
},
}A handler that throws never breaks the emitter or the handlers registered after it. Async handlers are started but not awaited — so a slow subscriber cannot slow down whatever emitted the event.
Lend a capability to AI agents. The platform passes the tenant scope, so a tool cannot read outside the conversation it is running in — this is enforced in code, not asked for in a prompt.
{
slot: "ai.tool",
value: {
id: "acme.loyalty.balance",
name: "check_points_balance",
description: "Return the contact's current loyalty points balance.",
parameters: [
{ name: "contactId", type: "string", description: "Contact id", required: true },
],
// scope is passed by the platform — a tool physically cannot read
// outside the tenant of the conversation it is running in.
execute: async (args, scope) => {
return getBalance(String(args.contactId), scope);
},
},
}Mark a tool mutates: true if it changes state. Agents can then be configured to confirm before running it.
Publish a node and it appears in the flow builder palette for every tenant with your plugin enabled — including in flows they have already built.
{
slot: "workflow.node",
value: {
id: "acme.loyalty.award",
kind: "action", // trigger | action | condition | loop | delay
label: "Award points",
category: "Loyalty", // groups it in the builder palette
description: "Add points to the contact in context.",
icon: Gift,
outputs: ["next", "failed"], // named ports the builder can connect
fields: [
{ key: "points", label: "Points", type: "number", required: true },
{ key: "reason", label: "Reason", type: "template" },
],
},
}Settings render as a form in tenant settings automatically. Fields marked secret are write-only and never returned by the API.
settings: [
{ key: "pointsPerRupee", label: "Points per rupee", type: "number", default: 1 },
{ key: "tierThresholds", label: "Tier thresholds", type: "json" },
{ key: "providerKey", label: "Provider API key", type: "password", secret: true },
],
featureFlags: [
{ key: "tiers", label: "Tier system", description: "Enable bronze/silver/gold tiers.", default: false },
],
apiEndpoints: [
{ method: "GET", path: "loyalty/balance/:contactId", summary: "Points balance.", permissions: ["crm.view"] },
{ method: "POST", path: "loyalty/award", summary: "Award points.", permissions: ["crm.manage"] },
]Test a plugin by emitting the events it subscribes to and asserting on the result. There is no need to boot a UI.
import { registry, eventBus, asTenantId } from "@shubham-ai/sdk";
import "./plugin"; // registers it
test("awards points when a payment completes", async () => {
const tenant = asTenantId("t_test");
eventBus.emit("payment.completed", {
paymentId: "pay_1", tenantId: tenant, amountMinor: 250_00, currency: "INR",
}, tenant, "test");
await flushMicrotasks();
expect(await getBalance("cnt_1", scope)).toBe(250);
});
test("declares valid dependencies", () => {
expect(registry.validate()).toEqual([]);
});Review looks for three things: that you do not import another plugin, that every tool and endpoint respects the tenant scope, and that mutating operations declare permissions. Those are the failures that would affect other tenants.
Ready to build?
Browse the existing plugins to see real contracts, or read the API reference for the endpoints you can call.