@spindlecommerce/plugin-sdk

The plugin API for SpindleCommerce. A plugin adds to the platform without changing its code: a payment or shipping provider, an email or ERP integration, a fraud check, GraphQL fields, HTTP routes or scheduled tasks. Staff switch plugins on and fill in their settings in the admin, under Settings › Plugins.

Writing a plugin

The quickest start is the template, spindlecommerce/plugin-hello-world. By hand:

pnpm add -D @spindlecommerce/plugin-sdk

// package.json
"peerDependencies": { "@spindlecommerce/plugin-sdk": "^1.0.0" }

import { definePlugin, setting } from "@spindlecommerce/plugin-sdk";

export const hello = () =>
  definePlugin({
    name: "hello",
    version: "1.0.0",
    apiVersion: 1,
    title: "Hello",
    settings: { greeting: setting.string({ label: "Greeting", default: "Hello" }) },
    events: {
      "order.placed": async (event, ctx) => ctx.logger.info({ orderId: event.aggregateId }, ctx.settings.greeting),
    },
  });

• The peer dependency matters. In an installation, @spindlecommerce/plugin-sdk is the platform's own SDK, and the peer dependency makes your plugin use it. Then errors such as PaymentDeclinedError are the ones the platform checks for.
• Write apiVersion as a number. Inside an installation PLUGIN_API_VERSION is the platform's own, so a plugin that used it would always claim to match.
• Publish JavaScript. Build with tsc to dist/. Installations load plugins from node_modules, where Node does not strip TypeScript types.
• Handlers run at least once. An event can be delivered again after a timeout. Use ctx.once for anything that must happen once, such as sending an email.

Installing a plugin

In an installation:

pnpm add @spindlecommerce/plugin-hello-world

// ecom.config.ts
import { helloWorld } from "@spindlecommerce/plugin-hello-world";

export default defineConfig({ plugins: [stripe(), email(), helloWorld()] });

Deploy, then open Settings › Plugins. A plugin starts working once every required setting has a value.

What's in it

• definePlugin, defineConfig, setting and PLUGIN_API_VERSION.
• The errors plugins throw: ValidationError, NotFoundError, InvalidStateError and PaymentDeclinedError.
• Types for every extension point: events, the checkout hook, error reports (onError), payment and shipping providers, HTTP routes, scheduled tasks, migrations and GraphQL.
• The handler context, PluginContext: settings, logger, key-value storage, once, emit, fetch and the platform's services.
  • The services cover orders, customers, channels, locations, and the catalog. The catalog gives products as a channel's storefront shows them, page by page, for feeds and syncs.

ctx.db is the platform's PostgreSQL database (Drizzle), for your plugin's own tables. In this package, ctx.platform and the GraphQL builder, refs and context have loose types. They are internal to the platform, and in an installation they have its precise types.

Versions

The major version is the plugin API version: 1.x is apiVersion: 1. A platform refuses, at startup, a plugin written for another API version. Minor versions add to the API without breaking plugins.

What 1.1 added:

• services.catalog;
• services.channels.getByCode and channels.list;
• the onError hook;
• phone and acceptsMarketing on customers;
• couponCodes on orders.

A plugin that uses any of them should peer-depend on ^1.1.0.

License

MIT