Skip to content
Documentation

Reference

Plugin SDK

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 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.

WhatsApp
CRM
AI Agents
Commerce
Billing
Your plugin

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.

Your first plugin

A plugin is one object. Everything beyond identity is optional, so a small plugin stays small.

acme-loyalty/plugin.ts
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.

typescript
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.

Extension slots

Eighteen surfaces you can extend. Each slot is typed, so a widget cannot be registered as a nav item.

SlotWhat it adds
sidebar.itemA navigation entry in a sidebar group
dashboard.widgetA card on the role dashboard
header.actionA button in the application top bar
table.columnAn extra column on a shared table
table.row_actionA per-row action in a table menu
table.bulk_actionAn action across selected rows
detail.sectionA panel on an entity detail page
detail.tabA tab on an entity detail page
profile.cardA card on a contact or tenant profile
report.blockA block available in report building
analytics.metricA metric the analytics module can chart
notification.channelA delivery channel for notifications
automation.triggerA trigger for the rules engine
workflow.nodeA node in the flow builder palette
ai.toolA capability AI agents can call
settings.sectionA section in tenant settings
command.paletteAn action in the command palette
onboarding.stepA step in the onboarding checklist

Events

Declare what you emit so the marketplace can show your contract, and subscribe to what you care about. Handlers are typed per event name.

typescript
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.

AI tools

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.

typescript
{
  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.

Workflow nodes

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.

typescript
{
  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, flags and endpoints

Settings render as a form in tenant settings automatically. Fields marked secret are write-only and never returned by the API.

typescript
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"] },
]

Testing

Test a plugin by emitting the events it subscribes to and asserting on the result. There is no need to boot a UI.

plugin.test.ts
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([]);
});

Publishing

  1. Bump the version following semver. Breaking changes are a major.
  2. Add release notes — they appear on your marketplace listing.
  3. Run the architecture checks: dependencies resolve, no cycles, semver is valid.
  4. Submit for review. We check the contract, not your business logic.

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.

Typed contractsNo privileged APIEvents, not importsTenant-scoped by default