@helmdesk/sdk 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,10 @@
 # @helmdesk/sdk
 
-Official Node.js SDK for the [Helmdesk](https://helmdesk.dev) API — helpdesk, transactional email, and knowledge base for developers.
+[![npm version](https://img.shields.io/npm/v/@helmdesk/sdk.svg)](https://www.npmjs.com/package/@helmdesk/sdk)
+[![license](https://img.shields.io/npm/l/@helmdesk/sdk.svg)](https://github.com/MoloksInc/helmdesk/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+
+The official Node.js/TypeScript SDK for [Helmdesk](https://helmdesk.dev) -- a unified helpdesk, transactional email gateway, and knowledge base built for developers.
 
 ## Install
 
@@ -8,56 +12,248 @@ Official Node.js SDK for the [Helmdesk](https://helmdesk.dev) API — helpdesk,
 npm install @helmdesk/sdk
 ```
 
-## Quick start
+## Quick Start
 
 ```ts
-import { HelmdeskClient } from '@helmdesk/sdk'
+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: "jane@example.com",
+});
+```
+
+## API Reference
 
-const helmdesk = new HelmdeskClient({
-  apiKey: process.env.HELMDESK_API_KEY!,
-})
+### Tickets
+
+Manage support tickets -- create, list, update, and reply.
+
+**List tickets**
+
+```ts
+const { tickets, total } = await helmdesk.tickets.list({
+  status: "open",
+  priority: "high",
+  search: "login",
+  page: 1,
+  limit: 25,
+});
+```
 
-// Send a transactional email (defaults to 'production' environment)
-await helmdesk.emails.send({
-  templateKey: 'welcome',
-  to: { email: 'user@example.com', name: 'Jane' },
-  variables: { activationUrl: 'https://...' },
-  environment: 'production', // optional: 'production' | 'staging' | 'development'
-})
+**Get a ticket**
 
-// Create a support ticket
+```ts
+const ticket = await helmdesk.tickets.get("ticket_id");
+// Returns full detail: messages, tags, customer info
+```
+
+**Create a ticket**
+
+```ts
 const ticket = await helmdesk.tickets.create({
-  subject: 'Cannot login',
-  body: 'Getting a 403 error...',
-  customerEmail: 'user@example.com',
-})
+  subject: "Billing question",
+  body: "I was charged twice for my last invoice.",
+  customerEmail: "user@example.com",
+  customerName: "Jane Doe",
+  priority: "high",
+  category: "billing",
+});
+```
+
+**Update a ticket**
+
+```ts
+const updated = await helmdesk.tickets.update("ticket_id", {
+  status: "resolved",
+  priority: "low",
+  category: "howto",
+});
+```
+
+**Add a message to a ticket**
+
+```ts
+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**
+
+```ts
+const result = await helmdesk.emails.send({
+  templateKey: "welcome",
+  to: { email: "jane@example.com", name: "Jane" },
+  variables: { activationUrl: "https://app.example.com/activate?token=abc" },
+  environment: "production",
+});
+```
+
+**Preview an email**
+
+```ts
+const { subject, html } = await helmdesk.emails.preview({
+  templateKey: "welcome",
+  variables: { activationUrl: "https://example.com" },
+});
+```
+
+**Get a template's variable schema**
+
+```ts
+const schema = await helmdesk.emails.getTemplateSchema("welcome");
+// schema.variables: [{ name: 'activationUrl', type: 'string', required: true }]
+```
+
+### Articles
+
+Search your published knowledge base articles.
 
-// Search knowledge base articles
-const results = await helmdesk.articles.search({ q: 'reset password' })
+```ts
+const { articles, total } = await helmdesk.articles.search({
+  q: "reset password",
+  category: "account",
+  page: 1,
+  limit: 10,
+});
+```
+
+### Customers
 
-// Import a Handlebars template
+Track and manage customer profiles across tickets and emails.
+
+**List customers**
+
+```ts
+const { customers, total } = await helmdesk.customers.list({
+  search: "jane",
+  plan: "pro",
+  page: 1,
+  limit: 25,
+});
+```
+
+**Get a customer**
+
+```ts
+const customer = await helmdesk.customers.get("customer_id");
+// Includes recentTickets array
+```
+
+**Upsert a customer**
+
+```ts
+const customer = await helmdesk.customers.upsert({
+  email: "jane@example.com",
+  name: "Jane Doe",
+  plan: "pro",
+  metadata: JSON.stringify({ companyId: "acme-123" }),
+});
+```
+
+## Error Handling
+
+All API errors throw a `HelmdeskError` with structured fields for programmatic handling.
+
+```ts
+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.
+
+```ts
+await helmdesk.emails.send(
+  {
+    templateKey: "order-confirmation",
+    to: { email: "buyer@example.com" },
+    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**
+
+```ts
 await helmdesk.emails.templates.import(
-  '<h1>Hello {{name}}</h1>',
-  'welcome.hbs',
-  { type: 'template' }
-)
+  '<h1>Welcome, {{name}}</h1><p>Thanks for signing up.</p>',
+  "welcome.hbs",
+  {
+    type: "template",
+    subject: "Welcome to {{brandName}}!",
+  }
+);
 ```
 
-## Resources
+**Account-scoped partial (shared across all projects)**
+
+```ts
+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?
 
-- `helmdesk.tickets` — create, list, get, update, addMessage
-- `helmdesk.emails` — send, preview, getTemplateSchema
-- `helmdesk.emails.templates` — import (project or account scope)
-- `helmdesk.articles` — search
+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.
 
-## Requirements
+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.
 
-- Node.js 18+ (uses native `fetch`)
-- Works in Deno, Bun, and Cloudflare Workers
+Helmdesk is $19/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.
 
-## Documentation
+## Links
 
-Full API docs at [helmdesk.dev/docs](https://helmdesk.dev/docs)
+- [Homepage](https://helmdesk.dev)
+- [Documentation](https://helmdesk.dev/docs)
+- [Pricing](https://helmdesk.dev/pricing)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helmdesk/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Official Node.js SDK for the Helmdesk API",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",