Extend OnGravy with plugins

OnGravy's plugin platform is the modern successor to Tally's TDL: a declarative manifest, a closed permission set, and a sandboxed runtime that audits every call. Ship voucher hooks, custom reports, dashboard widgets, exports, and webhooks without forking the codebase.

How a plugin works

1. 1
   Manifest

   A plain object — id, version, name, author, description, category, entrypoint, permissions, optional jurisdictions. This is the trust boundary. Whatever the manifest doesn't declare, the runtime literally won't let you call.
2. 2
   Registry

   Each plugin module calls registerPlugin(manifest, factory) at import time. The registry validates the id (regex), the version (SemVer), and every permission (closed set). Bad manifests fail fast at boot, not at runtime.
3. 3
   Sandbox

   On invocation, the runtime builds a context object that contains only the methods your manifest requested. Asked for read:vouchers but not write:vouchers? ctx.writeVoucherTags is undefined. There's no monkey-patching around this.
4. 4
   Audit trail

   Every invocation — success, denial, or error — appends one event to activity_events with the plugin id, version, caller user/business, jurisdiction, outcome, and duration. Admins can revoke a plugin's permissions with a single click and watch the audit log confirm it.

A worked example

Reproduced verbatim from plugins/sample-voucher-tagger/index.ts. This plugin auto-applies a high-value tag to every voucher of ₹50,000 or more.

import { registerPlugin } from '@/lib/plugins/registry';
import type { PluginManifest } from '@/lib/plugins/types';

const HIGH_VALUE_THRESHOLD_PAISE = 50_000 * 100;  // 50_00_000

const manifest: PluginManifest = {
  id:          'sample-voucher-tagger',
  version:     '1.0.0',
  name:        'High-Value Voucher Tagger',
  author:      'OnGravy',
  description: 'Auto-applies the "high-value" tag to vouchers worth ₹50K or more.',
  category:    'voucher',
  entrypoint:  'plugins/sample-voucher-tagger/index.ts',
  permissions: ['read:vouchers', 'write:vouchers'],
};

registerPlugin(manifest, () => async (ctx) => {
  if (!ctx.readVouchers || !ctx.writeVoucherTags) {
    return { ok: false, error: 'missing required permissions' };
  }
  const candidates = await ctx.readVouchers({
    minAmountPaise: HIGH_VALUE_THRESHOLD_PAISE,
  });
  const tagged: string[] = [];
  for (const v of candidates) {
    if (v.tags.includes('high-value')) continue;
    await ctx.writeVoucherTags(v.id, [...v.tags, 'high-value']);
    tagged.push(v.id);
  }
  return { ok: true, data: { taggedCount: tagged.length, tagged } };
});

Permission matrix

The complete, current set. 9 permissions in API v1. Adding a new permission is a host change — plugins cannot extend the set on their own.

FAQ