Installation and lifecycle

Prepare the runtime

The package must already be available to Node.js from the kernel environment. The install endpoint reads its manifest and creates the database records; it does not run npm install.

The management endpoints are registered on the platform or combined service path when plugin runtime registration is enabled. Use a backend exposing /api/admin/plugins and a session with platform-management context for mutations. An ordinary shop administrator cannot install or enable platform-wide code.

Install a package

POST /api/admin/plugins/install

curl "$SELLFORGE_ADMIN_URL/api/admin/plugins/install" \
  -H "Authorization: Bearer $SELLFORGE_PLATFORM_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"packageName":"@sellforge-plugin/hello"}'

Installation reads the manifest, creates the installed record and plugin schema, and runs migrations. The plugin initially remains disabled.

The body can also contain tenantId for installed-record context. This does not turn plugin activation into a merchant-level operation.

Enable and disable

Encode a scoped package name when using it as a route parameter:

curl -X POST \
  "$SELLFORGE_ADMIN_URL/api/admin/plugins/%40sellforge-plugin%2Fhello/enable" \
  -H "Authorization: Bearer $SELLFORGE_PLATFORM_SESSION"

Enabling loads the plugin into the running process. The equivalent /disable endpoint updates the installed state, detaches hooks, disposes managed intervals, and removes registered services in that process.

Inspect status

GET /api/admin/plugins returns a plugins array. Records include installed metadata, loaded, and last_error. loaded reflects the current process's runtime registry.

GET /api/admin/plugins/:name returns one record in plugin. The /settings subresource exposes declared settings to platform context, masking secret values.

Startup and failures

At boot, enabled plugins are loaded from the database. If startup registration throws, the loader records the error and disables that plugin while allowing the application to continue booting.

Hot-enabling uses a separate code path and returns an error when loading fails. Inspect both the installed record and the process logs after a failed enable request.

Uninstall

DELETE /api/admin/plugins/:name unloads the plugin and removes its installed record. Data is preserved by default.

Use ?drop_data=true only when the plugin schema and migration history should also be removed. In deployments with multiple processes, coordinate lifecycle changes across all processes that load the plugin.