Docs

TypeScript client SDK

Build custom apps on top of Lunnoa Automate with @lunnoa/client.

@lunnoa/client is the official TypeScript SDK for the Lunnoa Automate Public API. Use it to build portals, internal tools, chat UIs, and backends that talk to your deployment's agents, workflows, entities, queues, and knowledge.

The SDK is presentation-free at the core: no components or widgets. Optional headless React hooks live in @lunnoa/client/react (see React hooks). You bring your own UI framework and design system; the SDK provides typed data access, SSE agent chat streaming, and deployment-specific codegen.

Coding agents (Cursor, Claude Code): start with For agents and the packaged lunnoa-solution-design + lunnoa-client skills.

Requirements

Before you install, make sure you have:

  • Node.js 20 or newer (or any runtime with fetch and web streams)
  • A Lunnoa Automate deployment URL
  • Either a workspace API key (lna_…) or a user JWT

Install

Add the package to your app:

install.sh
npm install @lunnoa/client

Quickstart

Create a client against your deployment, then list entities. Expansion fields are optional extras: responses are minimal by default, so request what you plan to render.

quickstart.ts
import { LunnoaClient } from '@lunnoa/client';const lunnoa = new LunnoaClient({  baseUrl: 'https://lunnoa.your-company.example',  apiKey: process.env.LUNNOA_API_KEY, // lna_… (server-side only)});const { data: invoices } = await lunnoa.entities.list({  objectTypeSlug: 'invoice',  state: 'pending',  expansion: ['attributes'],});

A SuperAdmin creates API keys in Admin Space → API Keys, choosing the workspace and an RBAC role for the key's service account. Prefer a minimal custom role over Admin. See API authentication for key creation and security notes.

Authentication

Pick one pattern before you write UI code. Mixing them usually means a leaked key or broken permissions.

PatternCredentialWhere
A. Backend holds the keyapiKey: 'lna_…' via createServerClientYour server, background jobs, server-rendered pages
B. End users are Lunnoa usersUser JWT via createBrowserClient + lunnoa.auth.loginBrowser apps (CORS origin allowlisted)
server.ts
import { createServerClient } from '@lunnoa/client';const lunnoa = createServerClient({  baseUrl,  apiKey: process.env.LUNNOA_API_KEY,});

Full login, 2FA, refresh, SSO, and token-store details: Authentication.

Resources

Most namespaces map to the Public API surface. approvals uses the authenticated workspace API (see Approvals).

NamespacePurpose
authLogin, 2FA, refresh, SSO discovery, me, local logout
agents / tasks / agentChatAgents, task history, SSE chat streaming
workflows / executionsTrigger workflows and poll or wait for results
actionsRun a single catalogue action as an ad-hoc Execution (source: SDK)
entities / entityTypesObjects and their schemas / state machines
knowledgeKnowledge bases and documents
queues / queueItemsHuman-in-the-loop work items
approvalsRequest Approval inbox (workspace API)
variables / connections / projectsWorkspace configuration
workflowAppsResolve app/action IDs to labels and icons
discoveryFeature flags for the deployment's edition

List calls accept shared conventions: expansion (extra fields), filterBy, and pagination (page / pageSize). Many list resources also support async iteration (entities.iterate(...), queueItems.iterate(...)).

Browse every public operation on the API reference.

Guides in this section

GuideWhat you will do
AuthenticationLogin, refresh, SSO, token stores, auto-refresh
CodegenGenerate typed accessors for your deployment
For agentsCursor / Claude skills, paste block, short playbook
DiscoveryInspect the catalogue, agents, workflows, and entity schemas
EntitiesQuery, create, and change entity state
WorkflowsTrigger runs, render executionPath, resume NEEDS_INPUT
AgentsDefine, deploy, and run agents end to end
Run actionsCall one catalogue action as an ad-hoc SDK Execution
Define locallyAuthor typed define* factories (actions, workflows, agents)
Start runsRun linear steps as one multi-step SDK Execution
CLIDiscover the catalogue for a key, then upsert define* files by slug
Execution progressTimeline snapshots and live SSE watchProgress
Agent chatStream SSE chat in the AI SDK UIMessage format
QueuesWork through human-in-the-loop queue items
ApprovalsList pending approvals and decide
ErrorsHandle LunnoaApiError status helpers

Checklist for a new custom UI

Use this as a short go-live list once the SDK is wired in.

  1. Choose an auth pattern

    Confirm base URL and pattern A or B. Keep lna_ keys server-side only. For pattern B, use createBrowserClient and Authentication.

  2. Run codegen

    Run npx @lunnoa/client codegen against the deployment and commit the output. See Codegen.

  3. Adapt to features

    Call discovery.enabledFeatures() and hide unsupported areas. See Discovery.

  4. Build from schemas

    Drive forms and tables from attributeSchema / customInputConfig, or from the generated types.

  5. Handle workflow UX

    Render progress with executions.getProgress / watchProgress (see Execution progress). Resume NEEDS_INPUT with submitInput. See Workflows.

  6. Wire chat carefully

    Stream via SSE, handle resume and stop, load history from the task. See Agent chat.

  7. Handle API errors

    Map 401 to re-auth, 403 to hide the capability, and 429 to back off. See Errors.

Related