@servicem8/addon-kit
v1.0.1
Published
Build, test, and deploy ServiceM8 add-ons from your terminal.
Readme
@servicem8/addon-kit
Build, test, and deploy ServiceM8 add-ons from your terminal.
addon-kit is the command-line tool for the ServiceM8 Addon SDK. Scaffold an add-on, deploy it to the platform, and manage its secrets — without leaving your editor.
npx addon-kit init my-addon # scaffold an add-on project
cd my-addon
npx addon-kit login # authenticate with a ServiceM8 account API key
npx addon-kit deploy # ship it — live on your account in secondsInstallation
npm install -D @servicem8/addon-kit # per-project (recommended)
# or
npm install -g @servicem8/addon-kit # globalRequires Node.js 22+.
Commands
| Command | What it does |
|---------|--------------|
| addon-kit init [name] | Scaffold a new add-on project (TypeScript by default): addon.jsonc, an entry-point function, package.json. In a directory with a legacy manifest.json, offers an automatic migration. |
| addon-kit login | Prompt for a ServiceM8 account API key (full access required for deploys), validate it live, and store it in ~/.sm8/. Set SM8_API_KEY to authenticate in CI. |
| addon-kit logout | Remove the stored API key. |
| addon-kit whoami | Show the authenticated ServiceM8 account and the key's access level. |
| addon-kit deploy | Validate addon.jsonc, bundle your entry point (TypeScript, multiple files and npm dependencies all supported), and deploy. The add-on is activated on your account immediately. --dry-run validates and bundles without deploying. |
| addon-kit secret put/list/delete <NAME> | Manage add-on secrets. Secrets are delivered to your function as environment variables and apply immediately — no redeploy. Values are prompted, never passed as arguments. |
Every command documents itself: addon-kit <command> --help.
The config file: addon.jsonc
One file per add-on project — your manifest plus tooling settings, with comments:
{
"$schema": "./node_modules/@servicem8/addon-kit/addon-schema.json",
// The unique identifier for this add-on (lowercase, digits, hyphens).
// Deploys upsert on this — changing it creates a NEW add-on.
"slug": "job-weather",
// The customer-facing name shown in the Add-on Store.
"name": "Job Weather Forecast",
"version": "1.0",
// Entry point, bundled by addon-kit deploy (defaults to index.js).
"main": "src/index.ts",
"actions": [
{
"name": "Check Weather",
"type": "online",
"entity": "job",
"iconURL": "https://example.com/icon-512.png",
"event": "check_weather"
}
]
}The $schema reference gives you validation and autocomplete in your editor. All add-on manifest fields are supported with identical semantics — migrating an existing add-on is renaming manifest.json to addon.jsonc and adding a slug.
Your function
Add-ons run as serverless functions. addon-kit init scaffolds a working handler:
export const handler = async (event: SM8Event) => {
// event.eventName, event.eventArgs.jobUUID
// event.auth.accessToken — a short-lived token for the ServiceM8 REST API
return { eventResponse: "<html>…</html>" };
};addon-kit deploy bundles whatever your entry point imports — TypeScript, multiple files, npm packages — into a single artifact (up to 45 MB).
CI
# e.g. GitLab CI / GitHub Actions
- npm ci
- SM8_API_KEY=$SM8_API_KEY npx addon-kit deployLicense
MIT © ServiceM8