LabelInn Node.js SDK

Official Node.js SDK for the LabelInn Cloud Print API. Send labels to thermal printers (Zebra, TSC, Honeywell), manage your fleet, and build print automation workflows — all from code.

Zero dependencies. Uses Node.js 18+ built-in fetch.

Table of Contents

• Installation
• Quick Start
• Authentication
• Print Jobs
• Fleet Management
• Designs (Templates)
• Webhooks
• Data Connect
• Rate Limits
• Error Handling
• CLI Tool
• Configuration
• Requirements
• Contributing
• License

Installation

npm install labelinn

Quick Start

const LabelInn = require('labelinn');

// Use a test key for development (no real prints, no quota cost)
const client = new LabelInn('sk_test_xxxxx');

// Print a ZPL label
const job = await client.print.create({
  printer_id: 'prt_abc123',
  payload_type: 'zpl',
  payload_data: '^XA^FO50,50^ADN,36,20^FDHello World^FS^XZ',
});

console.log(`Job ${job.id} → ${job.status}`);

Authentication

Get your API key from LabelInn → Settings → API Keys.

| Key prefix | Mode | Description | |---------------|---------|------------------------------------| | sk_test_xxx | Sandbox | No real prints, separate quota | | sk_live_xxx | Live | Sends jobs to physical printers |

// Test mode — safe for development
const dev = new LabelInn('sk_test_xxxxx');
console.log(dev.isTestMode); // true

// Live mode — real prints
const prod = new LabelInn('sk_live_xxxxx');

Print Jobs

Send a ZPL label

const job = await client.print.create({
  printer_id: 'prt_abc123',
  payload_type: 'zpl',
  payload_data: '^XA^FO50,50^ADN,36,20^FDShipping Label^FS^XZ',
  copies: 2,
  job_name: 'Order #1234',
});

Send an image label

// From a URL (HTTPS only, max 500KB)
const job = await client.print.create({
  printer_id: 'prt_abc123',
  payload_type: 'image',
  image_url: 'https://example.com/labels/shipping.png',
});

Print from a template

const job = await client.print.create({
  printer_id: 'prt_abc123',
  payload_type: 'template',
  design_id: 'dsg_shipping_v2',
  data: {
    order_id: 'ORD-9876',
    customer: 'Ali Yilmaz',
    barcode: 'TR123456789',
  },
});

Idempotency (prevent duplicate prints)

const job = await client.print.create(
  { printer_id: 'prt_abc123', payload_type: 'zpl', payload_data: '...' },
  { idempotencyKey: 'order-9876-label' }
);
// Calling again with the same key returns the original job

List & manage jobs

// List recent jobs
const { jobs } = await client.print.list({ limit: 10 });

// Filter by status
const { jobs: failed } = await client.print.list({ status: 'failed' });

// Get job details
const job = await client.print.get('job_abc123');

// Cancel a queued job
await client.print.cancel('job_abc123');

// Reprint with different printer
await client.print.reprint('job_abc123', { printer_id: 'prt_backup' });

Fleet Management

// List all printers
const { printers } = await client.fleet.list();

// Filter by status
const { printers: online } = await client.fleet.list({ status: 'online' });

// Get printer details
const printer = await client.fleet.get('prt_abc123');

// Quick status check
const status = await client.fleet.status('prt_abc123');
console.log(`${status.status} — Paper: ${status.paper_status}`);

Designs (Templates)

// List designs
const { designs } = await client.designs.list();

// Get design with elements
const design = await client.designs.get('dsg_abc123');

// Create a design
const newDesign = await client.designs.create({
  name: 'Shipping Label v3',
  width_mm: 100,
  height_mm: 60,
});

// Add elements
await client.designs.addElement('dsg_abc123', {
  type: 'text',
  x: 10, y: 10,
  text: '{{order_id}}',
  font_size: 14,
});

await client.designs.addElement('dsg_abc123', {
  type: 'barcode',
  x: 10, y: 40,
  barcode_type: 'code128',
  data: '{{tracking_number}}',
});

// Clone a design
const clone = await client.designs.clone('dsg_abc123');

// Print directly from a design
await client.designs.print('dsg_abc123', {
  printer_id: 'prt_abc123',
  data: { order_id: 'ORD-5555', tracking_number: 'TR999' },
  copies: 1,
});

Webhooks

// Subscribe to events
const webhook = await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/labelinn',
  events: ['print_job.completed', 'print_job.failed', 'printer.offline'],
  description: 'Production monitoring',
});

// Save the signing secret!
console.log('Signing secret:', webhook.signing_secret);

// List subscriptions
const { webhooks } = await client.webhooks.list();

// Send a test ping
await client.webhooks.test(webhook.id);

// Unsubscribe
await client.webhooks.delete(webhook.id);

Verifying webhook signatures

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express handler:
app.post('/webhooks/labelinn', (req, res) => {
  const signature = req.headers['x-labelinn-signature'];
  const valid = verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET);
  if (!valid) return res.status(401).send('Invalid signature');

  const { event, data } = req.body;
  console.log(`Event: ${event}`, data);
  res.sendStatus(200);
});

Data Connect

Data Connect lets you ingest data from any enterprise system (SAP, Oracle, CSV exports, custom APIs) and print labels from it. Supports XML/IDoc, CSV/TSV, and JSON/NDJSON formats with auto-detection.

Ingest Data

// From a JSON payload
const result = await client.connect.ingest({
  source_id: 'src_abc123',
  payload: JSON.stringify([
    { sku: 'A001', name: 'Widget', qty: 10 },
    { sku: 'A002', name: 'Gadget', qty: 5 },
  ]),
  format: 'json',
});
console.log(`Ingested ${result.records_count} records`);

// From XML/IDoc
const xmlResult = await client.connect.ingest({
  source_id: 'src_sap',
  payload: xmlString,
  format: 'xml',
});

Test Parse (Dry Run)

const parsed = await client.connect.testParse({
  payload: csvString,
  format: 'csv',
});
console.log(`Detected ${parsed.records.length} records`);
console.log('Schema:', parsed.schema.map(f => f.path));

Manage Sources

// Create a source
const source = await client.connect.createSource({
  name: 'SAP Orders',
  format: 'xml',
});

// List all sources
const sources = await client.connect.listSources();

// Get source details
const detail = await client.connect.getSource('src_abc123');

// Update a source
await client.connect.updateSource('src_abc123', { name: 'SAP Orders v2' });

// Delete a source
await client.connect.deleteSource('src_abc123');

Schema & Records

// Get detected schema
const schema = await client.connect.getSchema('src_abc123');
schema.fields.forEach(f => console.log(`${f.path} (${f.type}): ${f.sample}`));

// List ingested records
const records = await client.connect.listRecords('src_abc123', 50);

Field Mappings

// Get current mappings
const mappings = await client.connect.getMappings('src_abc123');

// Update mappings
await client.connect.updateMappings('src_abc123', {
  sku: 'product_code',
  name: 'product_name',
});

Print from Connector

const printResult = await client.connect.print({
  source_id: 'src_abc123',
  design_id: 'dsg_shipping',
  printer_id: 'prt_warehouse1',
  copies: 1,
});
console.log(`Created ${printResult.count} print jobs`);

Rate Limits

Every response includes rate limit info:

const result = await client.print.list();
console.log(result._rateLimit);
// { limit: 2000, remaining: 1847, reset: 3600 }

| Plan | Daily Limit | |------------|-------------| | Pro | 2,000 | | Enterprise | 50,000 | | Test keys | 500 minimum |

When rate-limited, the SDK throws LabelInnRateLimitError:

const { LabelInnRateLimitError } = require('labelinn');

try {
  await client.print.create({ ... });
} catch (err) {
  if (err instanceof LabelInnRateLimitError) {
    console.log(`Rate limited. Retry in ${err.retryAfter}s`);
  }
}

Error Handling

const { LabelInnError } = require('labelinn');

try {
  await client.print.create({ ... });
} catch (err) {
  if (err instanceof LabelInnError) {
    console.error(`[${err.status}] ${err.code}: ${err.message}`);
    // err.raw contains the full response body
  }
}

CLI Tool

The SDK includes a CLI for quick testing:

# Set your API key
export LABELINN_API_KEY=sk_test_xxxxx

# Verify connectivity
npx labelinn test

# List printers
npx labelinn printers

# Print a ZPL label
npx labelinn print prt_abc123 --zpl "^XA^FO50,50^ADN,36,20^FDHello^FS^XZ"

# Print from a template
npx labelinn print prt_abc123 --design dsg_shipping --data '{"name":"Ali"}'

# List jobs
npx labelinn jobs

# Get raw JSON output
npx labelinn printers --json

# --- Data Connect ---
# List connected data sources
npx labelinn connect sources

# Ingest data from a file
npx labelinn connect ingest conn_abc123 --file data.csv

# Test-parse a local file
npx labelinn connect parse --file data.csv --format csv

Run npx labelinn --help for all commands.

Configuration

const client = new LabelInn('sk_test_xxxxx', {
  baseUrl: 'https://labelinn.com/v1',  // default
  timeout: 30000,                       // 30s default
});

Requirements

• Node.js 18+ (uses built-in fetch)
• No external dependencies

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

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

Links

• LabelInn Website
• API Documentation
• Python SDK
• Changelog
• Report a Bug

License

MIT — see LICENSE for details.