@lunnoa/toolkit

TypeScript SDK for building integration apps that run on Lunnoa Automate.

What is this?

@lunnoa/toolkit is the public npm SDK for defining Lunnoa Automate integration apps — the actions, triggers, connections, and input forms that appear in workflows and AI agents.

Use it when you are:

• Building a publishable app package (for example @lunnoa-automate/app-http) that a Lunnoa server installs at runtime
• Developing a custom private integration for your organization
• Reading types and factory helpers while working against the lunnoa_automate platform

The toolkit provides factories and types only. Your app's run handlers execute inside the Lunnoa Automate server, which supplies runtime services (database, HTTP, OAuth, logging, and more).

Installation

npm install @lunnoa/toolkit

For app packages, declare the toolkit as a peer dependency — do not bundle it. The host server resolves @lunnoa/toolkit from its own node_modules at runtime.

{
  "peerDependencies": {
    "@lunnoa/toolkit": "^1.0.0"
  }
}

Requirements: Node.js ≥ 20.

Quick start

A minimal app with one action:

import {
  createApp,
  createAction,
  createTextInputField,
} from '@lunnoa/toolkit';
import { z } from 'zod/v3';

const greet = createAction({
  id: 'hello_action_greet',
  name: 'Greet',
  description: 'Return a greeting for the given name.',
  inputConfig: [
    createTextInputField({
      id: 'name',
      label: 'Name',
      required: {
        missingMessage: 'Name is required',
        missingStatus: 'warning',
      },
    }),
  ],
  aiSchema: z.object({
    name: z.string().describe('Person to greet'),
  }),
  needsConnection: false,
  async run({ configValue }) {
    return { message: `Hello, ${configValue.name}!` };
  },
  async mockRun({ configValue }) {
    return { message: `Hello, ${configValue.name}!` };
  },
});

export default createApp({
  id: 'hello',
  name: 'Hello',
  description: 'A minimal example integration app.',
  logoUrl: 'https://example.com/logo.svg',
  actions: [greet],
  triggers: [],
  connections: [],
});

Export the createApp(...) result as your package default export. The platform loads installable apps with require() and registers them in the workflow app catalog.

Core concepts

App (createApp)

The top-level definition for an integration. Sets metadata (id, name, description, logoUrl), registers actions, triggers, and connections, and optionally defines webhook verification helpers.

• App id: unique kebab-case slug (for example http, slack, hello)
• Used as the registry key across workflows, connections, agents, and installed-app records

Action (createAction)

A single operation users (or agents) can invoke in a workflow or tool call.

| Field | Purpose | | --- | --- | | inputConfig | UI fields for configuring the action | | aiSchema | Zod schema mirroring inputConfig — used by agents and validation | | run | Executes the action; receives configValue, connection, and platform services | | mockRun | Returns representative output for workflow mapping and testing |

Action id format: <app-id>_action_<action-name> (for example http_action_send-request)

Trigger

Starts or schedules workflow runs. Factory helpers include:

| Factory | Strategy | | --- | --- | | createManualTrigger | Manual / on-demand | | createScheduleTrigger | Cron-style schedule | | createAppWebhookTrigger | App-level webhook listener | | createCustomWebhookTrigger | Custom webhook endpoint | | createItemBasedPollTrigger | Poll for new/changed items | | createLengthBasedPollTrigger | Poll when list length changes | | createTimeBasedPollTrigger | Poll on a time interval |

Trigger id format: <app-id>_trigger_<trigger-name> (for example flow-control_trigger_manually-run)

Connection

Authentication configuration for third-party APIs. Factory helpers:

| Factory | Type | | --- | --- | | createApiKeyConnection | API key | | createBasicAuthConnection | HTTP basic auth | | createOAuth2Connection | OAuth 2.0 | | createOAuthProvider | OAuth provider metadata | | createKeyPairConnection | Key pair / certificate | | createDatabaseConnection | Database credentials |

Connection id format: <app-id>_connection_<connection-name> (for example slack_connection_oauth2)

Input config builders

Helpers such as createTextInputField, createSelectInputField, createNumberInputField, createJsonInputField, and createDynamicSelectInputField build the inputConfig arrays shared by actions, triggers, and connections.

Types and utilities

The package also exports shared types (RunActionArgs, InputConfig, ConnectionType, trigger types, and more) and utilities for dates, JSON parsing, and workflow data handling. See src/index.ts for the full public surface.

Publishable app packages

Installable apps are npm packages with a default export of createApp({...}) and a lunnoaApp manifest block in package.json:

{
  "name": "@acme/lunnoa-app-my-service",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "peerDependencies": {
    "@lunnoa/toolkit": "^1.0.0"
  },
  "lunnoaApp": {
    "appId": "my-service",
    "toolkitVersion": "^1.0.0",
    "platformVersion": "^1.0.0"
  }
}

| Field | Description | | --- | --- | | lunnoaApp.appId | Must match createApp({ id }) exactly | | lunnoaApp.toolkitVersion | Compatible toolkit semver range | | lunnoaApp.platformVersion | Compatible Lunnoa Automate platform semver range |

SuperAdmins install packages on a running Lunnoa server via the admin API; no platform rebuild is required.

Examples and platform

| Resource | Description | | --- | --- | | lunnoa_automate | The Lunnoa Automate platform (server, UI, built-in apps) | | lunnoa_apps | Reference and publishable app packages built with this toolkit | | Lunnoa docs | Input config, triggers, and connection guides |

Built-in apps in the monorepo (packages/apps) use the same createApp contract. Installable app packages depend on the published npm version of this toolkit.

Need help building?

This toolkit is for developers who want to build integration apps themselves. If you need custom implementations, private integrations, or help designing and deploying AI agents on Lunnoa Automate, the Lunnoa team can help.

Typical engagements include:

• Custom app packages for your internal systems or SaaS tools
• OAuth connections, webhooks, and workflow automation tailored to your stack
• AI agents with tool calling, context blueprints, and production-ready guardrails
• Platform setup, self-hosting, and ongoing integration maintenance

Contact Lunnoa to discuss your use case, or start with the cloud app to explore the platform.

Versioning and stability

This package follows semantic versioning:

• Major — breaking changes to factory signatures, exported types, or ID conventions
• Minor — backward-compatible features (new factories, optional fields)
• Patch — bug fixes and non-breaking internal changes

The public factory API (createApp, createAction, trigger/connection factories, input-config builders) is treated as stable from 1.0.0 onward. Breaking changes ship only in major releases.

License

Licensed under Apache-2.0 with Commons Clause.

You may use, modify, and distribute the software under Apache 2.0 terms, with one additional restriction: you may not sell the software itself (the toolkit as a standalone product). Building and operating apps or services that use the toolkit is permitted. Consult your legal team before commercial redistribution of the SDK itself.

Development

git clone https://github.com/lunnoa-automate/lunnoa_toolkit.git
cd lunnoa_toolkit
pnpm install
pnpm build

Build output is written to dist/src/. The build runs prisma generate first (stub schema) so @prisma/client types resolve; the host platform provides the real Prisma client at runtime.

Only dist/ is included in the published npm tarball.

Publishing

Releases are fully automated with semantic-release. Maintainers do not bump versions, create tags, or publish from local machines.

How it works

1. Merge conventional commits to master (or main).
2. CI runs build and tarball validation.
3. On success, Release runs semantic-release, which:
   • Determines the next semver from commit messages
   • Updates package.json and CHANGELOG.md
   • Creates a Git tag (vX.Y.Z) and GitHub Release
   • Publishes to npm with public access

Release commits pushed back to the repo include [skip ci] to avoid duplicate workflow runs.

Commit message format

Use Conventional Commits so semantic-release can compute the version:

| Commit prefix | Version bump | Example | | --- | --- | --- | | fix: | Patch | fix: handle empty connection config | | feat: | Minor | feat: add createWebhookConnection factory | | feat!: or footer BREAKING CHANGE: | Major | feat!: rename createApp id validation |

Other common prefixes (docs:, chore:, ci:, refactor:, test:) do not trigger a release unless they include a breaking-change footer.

Examples:

feat: export RunTriggerArgs type for app authors

fix: parse ISO dates without timezone offset

feat!: require app id to match lunnoaApp.appId in manifest

BREAKING CHANGE: createAction run handlers no longer receive legacy context shape

First release

There are no release tags yet. The first successful semantic-release run will analyze commits on master and publish the computed version (starting from 0.0.0 if no prior tag exists). To land on 1.0.0, include a breaking-change commit (for example feat!: initial public npm release) or push an initial baseline tag v1.0.0 before merging releasable commits so later bumps start from 1.0.0.

npm trusted publishing (OIDC)

Publishing uses npm trusted publishers via GitHub Actions OIDC — no NPM_TOKEN secret is required.

On npmjs.com, configure a Trusted Publisher for GitHub Actions:

| Field | Value | | --- | --- | | Organization / user | lunnoa-automate | | Repository | lunnoa_toolkit | | Workflow filename | release.yml | | Environment | (leave empty unless you use a GitHub Environment) |

The release workflow grants id-token: write and uses semantic-release v25 (bundles @semantic-release/npm v13 with OIDC support) and Node 24 (npm 11.5.1+).

Required secrets

| Secret | Purpose | | --- | --- | | GITHUB_TOKEN | Provided by Actions; needs Contents: Read and write (default for release workflow) |

Dry run locally

pnpm install
pnpm exec semantic-release --dry-run

This analyzes commits and prints the next version without publishing or pushing.