npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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

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.