Zammad TypeScript API Client

A TypeScript wrapper client for the Zammad REST API, providing a clean and type-safe interface for managing tickets and other Zammad resources.

Features

• 🚀 TypeScript First: Built with TypeScript for better developer experience
• 🔐 Secure Authentication: Token-based authentication with environment variables
• 📦 Zero Dependencies: Only depends on axios for HTTP requests
• 🎯 Simple API: Clean and intuitive methods for common operations
• 🔄 Async/Await: Modern JavaScript with full async support

Installation

npm install zammad-typescript-api

Quick Start

1. Set Environment Variables

export ZAMMAD_HOST="https://your-zammad-instance.com"
export ZAMMAD_ACCESS_TOKEN="your_access_token_here"

2. Basic Usage

import getZammadClient from 'zammad-typescript-api';

// Get the client instance
const zammad = getZammadClient();

// Create a new ticket
const newTicket = await zammad.createTicket({
  title: 'Support Request',
  group: 'Users',
  customer_id: 1,
  article: {
    body: 'I need help with my account',
    type: 'web',
    internal: false
  }
});

// Get all tickets
const tickets = await zammad.getTickets();

// Get a specific ticket
const ticket = await zammad.getTicket(123);

// Update a ticket
await zammad.updateTicket(123, {
  title: 'Updated Support Request'
});

// Delete a ticket
await zammad.deleteTicket(123);

API Reference

ZammadHTTPClient

The main client class for interacting with the Zammad API.

Constructor

The client automatically reads configuration from environment variables:

• ZAMMAD_HOST: Your Zammad instance URL
• ZAMMAD_ACCESS_TOKEN: Your API access token

Methods

createTicket(ticketData: any)

Creates a new ticket in Zammad.

Parameters:

• ticketData: Object containing ticket information (title, group, customer_id, article, etc.)

Returns: Promise with the created ticket data

getTickets(params?: any)

Retrieves a list of tickets.

Parameters:

• params (optional): Query parameters for filtering tickets

Returns: Promise with array of tickets

getTicket(id: number)

Retrieves a specific ticket by ID.

Parameters:

• id: The ticket ID

Returns: Promise with ticket data

updateTicket(id: number, ticketData: any)

Updates an existing ticket.

Parameters:

• id: The ticket ID
• ticketData: Object containing updated ticket information

Returns: Promise with updated ticket data

deleteTicket(id: number)

Deletes a ticket.

Parameters:

• id: The ticket ID

Returns: Promise with deletion result

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | ZAMMAD_HOST | Your Zammad instance URL (e.g., https://help.yourcompany.com) | Yes | | ZAMMAD_ACCESS_TOKEN | Your Zammad API access token | Yes |

Error Handling

The client includes comprehensive error handling and will throw errors with detailed information when API calls fail. Errors include:

• Missing environment variables
• Authentication failures
• API request failures
• Network errors

Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/yourusername/zammad-typescript-api.git
cd zammad-typescript-api

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Scripts

• npm run build - Compiles TypeScript to JavaScript
• npm run test - Runs TypeScript type checking
• npm run clean - Removes the dist folder
• npm run prepare - Automatically runs build before npm publish

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

If you encounter any issues or have questions:

1. Check the issues page
2. Create a new issue with detailed information
3. Include your Zammad version and Node.js version

Changelog

1.0.0

• Initial release
• Basic ticket CRUD operations
• TypeScript support
• Environment variable configuration