Unitag API Client Library

A comprehensive, fully-typed TypeScript/JavaScript client library for the Unitag API v2. Generate, manage, and analyze QR codes with ease.

Features

• ✅ Full TypeScript support with comprehensive type definitions
• ✅ Complete API coverage: QR codes, domains, campaigns, filters, and analytics
• ✅ Modern async/await syntax
• ✅ Custom error handling with specific error types
• ✅ Works in Node.js and browsers
• ✅ Zero dependencies (except dev dependencies)
• ✅ Comprehensive test suite with Vitest
• ✅ Helper utilities for common tasks
• ✅ Production and sandbox environments

Installation

npm install unitag-api-client

yarn add unitag-api-client

pnpm add unitag-api-client

Quick Start

import { UnitagApi } from "unitag-api-client";

// Initialize the client
const api = new UnitagApi({
  apiKey: "your-api-key",
  sandbox: true, // Use sandbox for testing
});

// Create a QR code
const qrCode = await api.createQRCode({
  data: {
    type: "URL",
    resolution: "dynamic",
    url: "https://example.com",
    label: "My Website",
  },
});

console.log("QR Code created:", qrCode.short_url);

Getting Your API Key

• Sandbox (Testing): console.sandbox.unitag.io/settings
• Production: console.unitag.io/settings

Documentation

📚 Full Documentation - Comprehensive guides, API reference, and examples

Quick Links

• Getting Started Guide - Installation and first steps
• Configuration - Client setup and options
• Error Handling - Handling errors properly
• QR Codes API - QR code operations
• Examples - Code examples

Basic Usage

Create a QR Code

const qrCode = await api.createQRCode({
  data: {
    type: "URL",
    resolution: "dynamic",
    url: "https://example.com",
    label: "Example",
  },
  settings: {
    layout: {
      type: "gradient",
      gradient_type: "vertical",
      color_one: "#FF0000",
      color_two: "#0000FF",
    },
  },
});

Get All QR Codes

const result = await api.getQRCodes({
  maxRows: 10,
  page: 1,
  sortField: "creation_date",
  sortOrder: "desc",
});

console.log(`Total: ${result.total_records}`);

Download QR Code

const blob = await api.downloadQRCode({
  asset_uuid: "qrcode-uuid",
  format: "png",
  size: 500,
});

Get Analytics

const analytics = await api.getAnalytics({
  time_range: {
    type: 1,
    number: 7,
    unit: "days",
  },
});

console.log(`Visits: ${analytics.visits_count}`);

Error Handling

import {
  UnitagValidationError,
  UnitagRateLimitError,
  isUnitagError
} from 'unitag-api-client';

try {
  const qrCode = await api.createQRCode({...});
} catch (error) {
  if (error instanceof UnitagValidationError) {
    console.error('Validation failed:', error.details);
  } else if (error instanceof UnitagRateLimitError) {
    console.error('Rate limit exceeded. Retry after:', error.retryAfter);
  } else if (isUnitagError(error)) {
    console.error('Unitag API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

See the Error Handling Guide for comprehensive error handling patterns.

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import {
  UnitagApi,
  CreateQRCodeRequest,
  QRCodeData,
  Campaign,
  AnalyticsResponse
} from 'unitag-api-client';

const api = new UnitagApi({ apiKey: 'your-key' });
const qrCode: QRCodeData = await api.createQRCode({...});

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the library
npm run build

# Type checking
npm run typecheck

# Lint
npm run lint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

Links

• Documentation - Full documentation
• Unitag Official API Docs - Official Unitag API documentation
• Sandbox Console - Test environment
• Production Console - Production environment

Support

For issues related to this library, please open an issue.

For Unitag API support, contact Unitag through your console dashboard.