Hailer App SDK

@hailer/app-sdk is the client library for building Hailer Apps — web apps that run as an iframe inside the Hailer frontend. Your app instantiates one HailerApi client and calls the platform through it: users, workspaces, workflows, activities, files, insights, and more.

npm install @hailer/app-sdk

Because your app runs inside a host Hailer frame, runtime calls inherit the logged-in user's session — you never handle API tokens, passwords, or CORS at runtime. The SDK sends each call to the parent frame over postMessage; Hailer executes it with the current user's permissions and sends the result back.

import { HailerApi } from '@hailer/app-sdk';

const hailer = new HailerApi({
  connected: async () => {
    const me = await hailer.user.current();
    console.log(`Hello, ${me.firstname}`);
  },
});

How an app connects

An app is a web page Hailer loads in an iframe. On construction the SDK performs a handshake with the host frame, then calls your connected callback once the host is ready to receive calls. If the page is not running inside Hailer (opened standalone), the SDK falls back to outside mode and calls outside instead — only the hailer.public namespace works there.

See App lifecycle for the full handshake, callbacks, and modes.

What you can build

• Dashboards & views over workflow data — list, read, create, update, and print activities; read insights (reports); render kanban boards.
• Workspace tools — read workflows/teams/users/permissions, install workflow templates, manage document generation.
• UI extensions — command the host frame to open activity/discussion side panels, dialogs, and snackbars.
• Integrations — call allow-listed external HTTP/WebSocket endpoints through an authenticated proxy in the host frame.
• Public (logged-out) apps — public forms, public insights, and marketplace lookups that work without a Hailer session.
• Marketplace products — publish and price apps/templates via the product and payment modules.

The two halves of the package

Half	What it is	Auth
Runtime client (HailerApi)	The typed API your app calls in the browser, proxied through the host frame.	None — rides the host user's session.
Publish CLI (lib/tools/publish.cjs)	Pushes your built bundle to a Hailer instance or the marketplace.	Needs a --user-api-key (or --email + password).

This section documents the runtime client in depth. For pushing a build, see Publishing.

When to reach for the App SDK

Reach for the App SDK when you're building an app that lives inside Hailer and acts as the current user. For workspace configuration as code (creating/editing workflows, fields, and phases from your own machine), use the Hailer SDK CLI instead. The App SDK is about what runs inside Hailer; the Hailer SDK is about shaping the workspace from outside.

Module map

The HailerApi instance exposes these modules. Each has an API page documenting every method, its arguments, and its host-side behavior.

Module	Purpose
hailer.user	Current user, look up users, list workspace members.
hailer.workspace	Current/available workspaces, create workspaces, product installs.
hailer.workflow	List/get workflows, install workflow templates.
hailer.activity	CRUD + print activities; kanban and ball sub-modules.
hailer.team	Teams grouped by workspace.
hailer.permission	The current user's permission map.
hailer.file	Get/upload files, add/remove tags.
hailer.insight	List insights and read their data.
hailer.app	Marketplace lookups for the running app; app config updates.
hailer.product	CRUD on your own marketplace products.
hailer.metrics	Read usage metrics.
hailer.http	Authenticated proxy: fetch, upload, openWebSocket.
hailer.public	Endpoints callable without a session (the only namespace in outside mode).
hailer.ui	Command the host frame: open panels, dialogs, snackbars.
hailer.payment	Pricing and purchases (marketplace). Internal.
hailer.admin	Instance-admin endpoints. Internal — not for third-party apps.

Next steps

• Getting started — scaffold a project and make your first call.
• App lifecycle — the handshake, callbacks, and inside/outside modes.
• Private vs workspace apps — the scoping model that changes what almost every method returns.
• API — every module and method.
• Types — the exported type catalogue.