opscms-sdk
v0.1.16
Published
The SDK for building plugins that load on the OpsCMS platform: how a plugin describes itself, what it can ask the platform for, and what it can carry (notification channels).
Maintainers
Readme
opscms-sdk
The SDK for building plugins that load on the OpsCMS platform.
A plugin carries out work the platform's automation asks of it, in the shape it declares it accepts. It does not own a workflow or a message template (those belong to the platform's automation), and it does not decide when it runs. This package is the whole contract between a plugin and the platform:
| You | Use |
|---|---|
| Describe the plugin (name, category, version history) | definePluginManifest |
| Add collections, endpoints, jobs to the platform | definePlugin |
| Restrict a collection to a site's own data | access.siteScopedRead() and friends, tenancy.pinSite / tenancy.pinOrganization |
| Look up a site, ask if a plugin is installed, throttle a public endpoint | platform().sites, platform().plugins, platform().rateLimit |
| Get the platform's own treatment of your collections (locale switcher, activity log) | automatic: definePlugin applies platform().collections.wrap |
| Tell automation something happened | platform().automation.emitSystemEvent (and ensureEventHandler) |
| Carry a notification channel (WhatsApp, SMS) | registerNotificationChannel, or definePlugin({ notificationChannels }) |
| Create the tables the plugin needs | definePlugin({ migrations }), written with sqlMigration |
| Offer a step to workflows | definePlugin({ workflowSteps }): the step's input fields and its handler |
| Keep the plugin's per-site settings and keys | settingsCollection, with secretField for secrets and loadSettings to read them back (see Settings and keys) |
| Carry a payment gateway | definePlugin({ paymentProviders }), with the provider's own settings collection (see Settings and keys) |
A plugin never imports the platform's own code. The platform registers its services once, at start, with
registerPlatform(services); plugin modules build their access rules and hooks before that happens, so the helpers here look
the service up when a request arrives, not when the module loads.
A plugin in full
import { access, definePlugin, definePluginManifest, platform, tenancy } from 'opscms-sdk'
const manifest = definePluginManifest({
key: 'guestbook',
name: 'Guestbook',
description: 'Visitors leave a message on the site.',
category: 'content',
icon: 'icon.svg',
releases: [{ version: '1.0.0', date: '2026-11-07', notes: ['First release.'] }],
})
export const guestbookPlugin = definePlugin({
manifest,
collections: [
{
slug: 'guestbook-entries',
access: { read: access.siteScopedRead(), create: access.siteScopedCreate, update: access.siteScopedUpdate(), delete: access.siteScopedDelete() },
fields: [
{ name: 'message', type: 'textarea', required: true },
{ name: 'site', type: 'relationship', relationTo: 'sites', required: true, hooks: { beforeValidate: [tenancy.pinSite] } },
{ name: 'organization', type: 'relationship', relationTo: 'organizations', required: true, hooks: { beforeValidate: [tenancy.pinOrganization] } },
],
},
],
})Declare the package an OpsCMS plugin in its package.json ("opscms": { "plugin": true }) and list icon.svg (or .png) in files: the
platform checks the declaration before any of the package's code runs, and shows the logo on the plugin's card.
Versions are Major.Minor.Fixes. The version is never typed: it is the newest entry of releases.
Settings and keys
Every plugin keeps its own settings in its own collection. Not inside another plugin's, not in a table shared with other plugins: a plugin's table is shaped by what the plugin needs, no plugin ever holds another's keys, and the table goes when the plugin does.
import { definePlugin, loadSettings, secretField, settingsCollection, sqlMigration } from 'opscms-sdk'
const SLUG = 'guestbook-settings'
const GuestbookSettings = settingsCollection({
slug: SLUG, label: 'Guestbook settings', plural: 'Guestbook settings', group: 'Guestbook',
description: 'How this site\'s guestbook behaves.',
fields: [
{ name: 'moderated', type: 'checkbox' },
secretField(SLUG, 'webhookSecret', { label: 'Webhook secret', description: 'Signs notifications.' }),
],
})
// in a request, a job or an endpoint: the row of the site you are working for, secrets decrypted (the API only ever shows a mask)
const row = await loadSettings(payload, SLUG, siteId, ['webhookSecret'])settingsCollection gives the table what the platform expects of one: a row per site (unique on the site), readable and changeable
by admins of that site and the platform owner only, hidden from everyone else, and the site and organization fields kept to the
caller's tenant. secretField encrypts the value under the key of the site it belongs to before it is saved, shows a mask back,
keeps the stored value when the form is saved with the mask, and clears it when emptied. You never see the key.
The table itself is yours to create. Ship its SQL as a migration (sqlMigration) and drop it in that migration's down, so removing
the plugin removes its settings.
A payment gateway
A payment plugin adds its own settings collection (its switch, test or live mode, and whatever inputs its provider needs: a provider with more inputs than another needs no change anywhere else) and a provider that names it:
const provider: PaymentProvider = {
key: 'fastpay', label: 'FastPay', settingsCollection: 'fastpay-settings',
currencies: ['NGN'], requiredCredentials: ['secretKey'], endpoints: { test: 'https://sandbox.fastpay.example', live: 'https://api.fastpay.example' },
start, verify, readWebhook,
}
export const fastpayPlugin = definePlugin({ manifest, collections: [FastPaySettings], paymentProviders: [provider], migrations })The settings collection is built for you: paymentSettingsCollection(provider, { label, fields }) adds the switch, test or live mode, the address in use, the currency, the platform owner's address override and the webhook address around your own inputs. parseJson, toMajor, minorFromProviderMajor and minorFromProviderMinor read what a gateway answers with.
The platform starts the payment, believes only what the provider itself says when asked over its own API (verify), and settles the
order once. The provider's keys reach it as PaymentCredentials, read from the collection settingsCollection names, with enabled,
mode (test or live), currency, baseUrl (the provider address, platform owner only) and the secrets decrypted. Name the fields
of your collection after the credentials you use (secretKey, apiKey, publicKey, merchantId, contractCode, country) and add
enabled, mode and currency; definePlugin refuses a provider whose settings collection the plugin does not add.
Outside a platform
platform() throws a clear message when no platform has registered, so a plugin fails at the first use with a reason, not
later with a confusing error. hasPlatform() tells you whether one is there.
The full plugin directive is served by the platform at /docs (and as plain markdown at /docs/plugin-directive.md); it is also in the platform repo at payload-cms/docs/plugin-directive.md.
