@helmdesk/sdk

The official Node.js/TypeScript SDK for Helmdesk -- a unified helpdesk, transactional email gateway, and knowledge base built for developers.

Install

npm install @helmdesk/sdk

Quick Start

import { HelmdeskClient } from "@helmdesk/sdk";

const helmdesk = new HelmdeskClient({ apiKey: process.env.HELMDESK_API_KEY! });

const ticket = await helmdesk.tickets.create({
  subject: "Cannot login",
  body: "Getting a 403 error on the dashboard.",
  customerEmail: "[email protected]",
});

API Reference

Tickets

Manage support tickets -- create, list, update, and reply.

List tickets

const { tickets, total } = await helmdesk.tickets.list({
  status: "open",
  priority: "high",
  search: "login",
  page: 1,
  limit: 25,
});

Get a ticket

const ticket = await helmdesk.tickets.get("ticket_id");
// Returns full detail: messages, tags, customer info

Create a ticket

const ticket = await helmdesk.tickets.create({
  subject: "Billing question",
  body: "I was charged twice for my last invoice.",
  customerEmail: "[email protected]",
  customerName: "Jane Doe",
  priority: "high",
  category: "billing",
});

Update a ticket

const updated = await helmdesk.tickets.update("ticket_id", {
  status: "resolved",
  priority: "low",
  category: "howto",
});

Add a message to a ticket

const message = await helmdesk.tickets.addMessage("ticket_id", {
  body: "We've fixed the issue. Please try again.",
});

Emails

Send transactional emails using Handlebars templates managed in your Helmdesk dashboard.

Send an email

const result = await helmdesk.emails.send({
  templateKey: "welcome",
  to: { email: "[email protected]", name: "Jane" },
  variables: { activationUrl: "https://app.example.com/activate?token=abc" },
  environment: "production",
});

Preview an email

const { subject, html } = await helmdesk.emails.preview({
  templateKey: "welcome",
  variables: { activationUrl: "https://example.com" },
});

Get a template's variable schema

const schema = await helmdesk.emails.getTemplateSchema("welcome");
// schema.variables: [{ name: 'activationUrl', type: 'string', required: true }]

Articles

Search your published knowledge base articles.

const { articles, total } = await helmdesk.articles.search({
  q: "reset password",
  category: "account",
  page: 1,
  limit: 10,
});

Error Handling

All API errors throw a HelmdeskError with structured fields for programmatic handling.

import { HelmdeskClient, HelmdeskError } from "@helmdesk/sdk";

try {
  await helmdesk.tickets.get("nonexistent_id");
} catch (err) {
  if (err instanceof HelmdeskError) {
    console.error(err.status);  // 404
    console.error(err.code);    // 'not_found'
    console.error(err.message); // 'Ticket not found'
  }
}

Idempotency

The emails.send() method accepts an optional idempotencyKey to safely retry email sends without duplicates. If a request with the same key has already been processed, the API returns the original result.

await helmdesk.emails.send(
  {
    templateKey: "order-confirmation",
    to: { email: "[email protected]" },
    variables: { orderId: "ORD-4821" },
  },
  { idempotencyKey: "order-4821-confirmation" }
);

Template Import

Import Handlebars .hbs files as templates, layouts, or partials directly from your codebase or CI pipeline.

Project-scoped template

await helmdesk.emails.templates.import(
  '<h1>Welcome, {{name}}</h1><p>Thanks for signing up.</p>',
  "welcome.hbs",
  {
    type: "template",
    subject: "Welcome to {{brandName}}!",
  }
);

Account-scoped partial (shared across all projects)

await helmdesk.emails.templates.import(
  '<footer>{{companyName}} | {{unsubscribeLink}}</footer>',
  "footer.hbs",
  {
    type: "partial",
    scope: "account",
  }
);

Import options:

| Option | Type | Description | |---|---|---| | type | 'template' \| 'layout' \| 'partial' | File type. Defaults to 'template'. | | scope | 'project' \| 'account' | Project-scoped or shared across all projects. Defaults to 'project'. | | key | string | Override the template key. Defaults to the filename without .hbs. | | name | string | Override the display name. | | subject | string | Subject line. Can also be set via a {{!-- subject: ... --}} comment in the template. |

Runtime Support

The SDK uses the native fetch API with no Node.js-specific dependencies.

• Node.js 18+
• Deno
• Bun
• Cloudflare Workers

Why Helmdesk?

Most helpdesk tools are built for sales teams, not developers. They charge per seat, lock AI behind usage fees, and offer no API-first workflow.

Intercom starts at $29/seat with an additional $0.99 per AI resolution. HelpScout charges $25/user plus $0.75 per AI interaction. Crisp costs $95/workspace for their business tier.

Helmdesk is $29/month for up to 5 projects. AI features are included at every tier -- no per-resolution fees, no per-seat pricing. You get a helpdesk, transactional email gateway, and knowledge base in one platform with a full API and this SDK from day one.

Links

• Homepage
• Documentation
• Pricing

License

MIT