hailer-sdk

CLI toolkit for Hailer workspace development - initialize projects, manage workflows, and generate TypeScript types.

Features

• 🚀 Project initialization - scaffold new Hailer projects with best practices
• 📦 Workflow management - pull/push workflow configurations between Hailer and local files
• 🎯 Type generation - generate TypeScript types and enums from workflows and insights
• 🔐 Secure authentication - credential management with environment variables
• 📝 TypeScript-first - full type safety with generated definitions
• 🌐 Multi-environment support - connect to production or local development Hailer instances
• 🧪 Testing support - Vitest setup with test templates for function fields

Getting Started

1. Initialize a new project

Create a new Hailer project with proper structure and configuration:

npx @hailer/sdk@latest init

This interactive wizard will:

• Let you choose between production or local development API
• Authenticate with your Hailer account
• Let you select a workspace or create a new one
• Let you choose if you want to create a bot user and add it to your workspace
• Let you choose if you want to set up the MCP server in your project
• Create project structure with TypeScript configuration
• Set up environment variables and .gitignore
• Copy type definitions

After initialization, navigate to your project:

cd my-project
npm install

If you chose to set up the MCP server, the npm install step will automatically install the @hailer/mcp package and copy the .claude/ and .opencode/ configuration via the postinstall script.

Start the MCP server with:

npm run mcp-start

Then open a new terminal and start Claude Code to interact with your MCP server.

2. Pull workflows from Hailer

Use the npm script created during initialization:

npm run pull

This generates:

• workspace/enums.ts - Type-safe enums for workflow, field, phase, and member IDs
• workspace/groups.ts - Definitions for user groups in the workspace
• workspace/insights.ts - Insight definitions
• workspace/teams.ts - Team definitions
• workspace/apps.ts - App configurations
• workspace/workflows.ts - Registry of all workflows
• workspace/WorkflowName_id/ - Individual workflow folders containing:

  • main.ts - Workflow configuration

  • fields.ts - Field definitions

  • phases.ts - Phase definitions

  • functions/ - Extracted function fields (if workflow has calculated fields)

  • main.test.ts - Test template for function fields (generated once, editable)

3. Start developing!

You now have type-safe workflow definitions ready to use in your project.

Examples

Here are common tasks you'll perform after initializing your project:

Example 1: Creating a New Workflow

After initialization, you can create a new workflow from scratch:

1. Pull existing workflows to see the structure:

   npm run pull

2. Add the workflow to the registry in workspace/workflows.ts:

   export const workflows: HailerWorkflow[] = [
     // ... existing workflows
     {
       name: "My new workflow",
       // When `unlinkedMode` is enabled it will create a dataset, when disabled it will create a workflow
       enableUnlinkedMode: false,
     }
   ];

3. Sync the workflows:

   npm run workflows-sync

4. Pull from Hailer to generate the new workflow folder:

   npm run pull

To remove a workflow, delete it from the array and sync again.

5. Create phases workspace/Customer_Support_new_workflow_id_12345/phases.ts:

   import type { HailerPhaseUpdatePayload } from "../hailer";
   
   export const phases: HailerPhaseUpdatePayload[] = [
     {
       name: "New",
     },
     {
       name: "In Progress",
     },
     {
       name: "Resolved",
     },
   ];

6. Create fields workspace/Customer_Support_new_workflow_id_12345/fields.ts:

   import type { HailerField } from "../hailer";
   
   export const fields: HailerField[] = [
     {
       label: "Customer Email",
       type: "text",
       required: true,
     },
     {
       label: "Issue Type",
       type: "textpredefinedoptions",
       data: ["Bug", "Feature Request", "Question"],
       required: true
     },
   ];

7. Push to Hailer:

   npm run push

8. Pull from Hailer to get get the newly pushed fields and phases:

   npm run pull

Example 2: Adding a New Phase to an Existing Workflow

1. Pull the latest configuration:

   npm run pull

2. Edit the phases file for your workflow (e.g., workspace/MyWorkflow_abc123/phases.ts):

   export const phases: HailerPhaseUpdatePayload[] = [
     {
       name: "Draft",
       isInitial: true,
     },
     {
       name: "Pending",
     },
     {
       name: "Done",
       isEndpoint: true,
     },
   ];

3. Push only phases (faster than pushing everything):

   npm run phases-push

4. Pull to sync the generated IDs:

   npm run pull

To remove a phase, delete it from the array and push again.

Example 3: Modifying Workflow Settings

1. Pull the latest configuration:

   npm run pull

2. Edit workflow configuration in workspace/MyWorkflow_abc123/main.ts:

   export const workflow: HailerWorkflow = {
     _id: "abc123",
     name: "Updated Workflow Name",
     description: "Updated description",
     nameFunctionEnabled: true,
     nameFunction:"return 'This will be a name to all the activities in this workflow';"
   };

3. Push only workflow configs:

   npm run workflows-push

Example 4: Adding Custom Fields to a Workflow

1. Pull the latest configuration:

   npm run pull

2. Edit the fields file workspace/MyWorkflow_abc123/fields.ts:

   export const fields: HailerField[] = [
     // ... existing fields
     {
       label: "Total price",
       type: "numericunit",
       required: true,
       unit: "€",
     },
     {
       label: "Due Date",
       type: "date",
       required: false,
     },
   ];

3. Push only fields:

   npm run fields-push

4. Pull to get generated field IDs:

   npm run pull

To remove a field, delete it from the array and push again.

Example 5: Managing Workspace Groups

1. Pull the latest configuration:

   npm run pull

2. Add group in workspace/groups.ts:

   export const groups: HailerGroup[] = [
     {
       name: "Product Managers",
       members: ["user_id_3", "user_id_4"],
     },
   ];

3. Push groups:

   npm run groups-push

To remove a group, delete it from the array and push again.

Example 6: Managing Workspace Teams

1. Pull the latest configuration:

   npm run pull

2. Add team in workspace/teams.ts:

   export const teams: HailerTeam[] = [
     {
       name: "Support Team",
       members: ["user_id_5", "user_id_6"],
     },
   ];

3. Push teams:

   npm run teams-push

To remove a team, delete it from the array and push again.

Example 7: Managing Workspace Apps

1. Pull the latest configuration:

   npm run pull

2. Add app in workspace/apps.ts:

   export const apps: HailerAppUpdatePayload[] = [
     {
       // Leave _id empty for new apps
       name: "Sales Dashboard",
       description: "Custom dashboard for sales team",
       url: "https://dashboard.example.com",
       members: [
         {
           id: WorkspaceTeams.Sales_Team,
           type: "team"
         }
       ],
     },
   ];

3. Push apps:

   npm run apps-push

4. Pull to get the generated app ID:

   npm run pull

To remove an app, delete it from the array and push again.

Example 8: Using Generated Enums

After pulling, use the generated enums for type-safe IDs:

import {
  WorkflowIds,
  MyWorkflow_FieldIds,
  MyWorkflow_PhaseIds,
  WorkspaceMembers
} from "./workspace/enums";

// Use enums instead of hardcoded IDs
const workflowId = WorkflowIds.CustomerSupport;
const fieldId = MyWorkflow_FieldIds.CustomerEmail;
const phaseId = MyWorkflow_PhaseIds.InProgress;
const assignee = WorkspaceMembers.John_Doe;

Git

One of the intention of this SDK is to keep all workflow configurations in code and under version control. If you would like to setup git for your newly created you should create a new repository on GitHub or GitLab and then follow the instructions to push an existing repository from the command line.

Commands

For detailed documentation on all available commands, see:

• init - Initialize new projects
• generate - Generate TypeScript types
• ws-config - Manage workspace configurations

Common Options

Most commands support these options:

| Option | Alias | Description | | ----------------------- | ----- | -------------------------------------------- | | --email <email> | -e | Hailer account email | | --password <password> | -p | Hailer account password | | --workspace <id> | -w | Workspace ID | | --api-url <url> | -a | API URL (defaults to https://api.hailer.com) | | --verbose | | Show detailed logging | | --force | | Skip confirmation prompts (ws-config only) |

Development

Run locally without building

npm run dev -- init
npm run dev -- ws-config pull -e email -w workspace-id

Project Structure

src/
├── cli/
│   ├── index.ts              # CLI entry point
│   └── commands/
│       ├── init.ts           # Project initialization
│       ├── workspace-config.ts # Workflow pull/push
│       └── generate.ts       # Type generation
├── lib/
│   ├── actions/              # Command implementations
│   ├── hailer-client.ts      # API client
│   ├── generator.ts          # Type generation logic
│   └── helpers/              # Utility functions
└── types/
    └── hailer.d.ts           # Core type definitions

Troubleshooting

Permission denied when running CLI

After building, make sure the CLI is executable:

npm run build
chmod +x dist/cli/index.js
npm link

"Unknown file extension .ts" error

This happens when the CLI tries to import TypeScript files from user projects. Make sure jiti is installed as a dependency (not devDependency).

Authentication fails

• Verify credentials are correct
• Check environment variables are loaded