Plugin SDK Reference

jiffoo-plugin-sdk is the supported package for building Jiffoo Mall plugins. It shares the same manifest contract as the platform installer, so manifest.json validation is consistent between local SDK tooling and Admin upload.

Installation

npm install jiffoo-plugin-sdk

Core Exports

definePlugin(): declare an in-process plugin with register(ctx) and ctx.registerRoute(...)
createContextMiddleware(): extract platform headers into req.pluginContext
createSignatureMiddleware() / verifySignature(): verify signed platform requests
defineLifecycleHooks(): expose POST /__lifecycle/:hookName handlers for external-http plugins
validateManifest(): validate manifest.json against the shared authoritative contract

Manifest Contract

interface PluginManifest {
  schemaVersion: 1;
  slug: string;
  name: string;
  version: string;
  description: string;
  runtimeType: 'internal-fastify' | 'external-http';
  permissions: string[];
  entryModule?: string;
  externalBaseUrl?: string;
  category?: PluginCategory;
  capabilities?: string[];
  minApiVersion?: string;
  sdkVersion?: string;
  requiredApiVersion?: { min?: string; max?: string; exact?: string };
  lifecycle?: {
    onInstall?: boolean;
    onEnable?: boolean;
    onDisable?: boolean;
    onUninstall?: boolean;
    onUpgrade?: boolean;
  };
  themeExtensions?: {
    blocks?: Array<{
      extensionId: string;
      name: string;
      schema?: Record<string, unknown>;
      dataEndpoint?: string;
    }>;
    embeds?: Array<{
      extensionId: string;
      name: string;
      targetPosition: 'head-end' | 'body-end';
      schema?: Record<string, unknown>;
      dataEndpoint?: string;
    }>;
  };
}

Contract notes:

entryModule is required for internal-fastify
externalBaseUrl is required for external-http
minApiVersion is the platform-facing compatibility floor
requiredApiVersion is optional structured compatibility metadata used by SDK helpers
sdkVersion, version, and requiredApiVersion.* use strict validation

Define a Plugin

import { definePlugin } from 'jiffoo-plugin-sdk';

export const plugin = definePlugin({
  manifest: {
    id: 'my-plugin',
    version: '1.0.0',
    contract: 'v1',
    uses: ['api'],
  },
  register(ctx) {
    ctx.registerRoute({
      method: 'GET',
      path: '/store/status',
      handler: async () => ({ ok: true }),
    });
  },
});

The contract plugin manifest is loaded from plugin source code. The uploaded package still includes a manifest.json for installer validation:

{
  "schemaVersion": 1,
  "slug": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Example Jiffoo plugin",
  "runtimeType": "external-http",
  "externalBaseUrl": "https://my-plugin.example.com",
  "permissions": [],
  "category": "integration",
  "capabilities": ["webhook.receive"],
  "minApiVersion": "v1",
  "sdkVersion": "1.2.0"
}

Lifecycle Hooks

import { defineLifecycleHooks } from 'jiffoo-plugin-sdk';

const lifecycle = defineLifecycleHooks({
  onInstall: async (context) => {
    console.log(`Install ${context.installationId}`);
  },
  onUpgrade: async (context) => {
    console.log(`Upgrade from ${context.previousVersion}`);
  },
});

Mount it at POST /__lifecycle/:hookName and declare the matching booleans in manifest.json.

Local Validation

import { validateManifest } from 'jiffoo-plugin-sdk';

const result = validateManifest({
  schemaVersion: 1,
  slug: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',
  description: 'Example plugin',
  runtimeType: 'external-http',
  externalBaseUrl: 'https://my-plugin.example.com',
  permissions: [],
});

if (!result.valid) {
  console.error(result.errors);
}

Or via CLI:

npx jiffoo-plugin-sdk validate --manifest ./manifest.json

Compatibility Metadata

Use minApiVersion when you want the platform to enforce a minimum supported API version during install or enable. Use requiredApiVersion only when you need the SDK’s semver-based compatibility helpers for external tooling.

Plugin SDK

On this page