linkbreakers

Official TypeScript/JavaScript SDK for the Linkbreakers API.

Installation

npm install linkbreakers

Usage

import { Configuration, LinksApi } from 'linkbreakers';

// Configure API client
const config = new Configuration({
  accessToken: 'your_api_key_here',  // Use accessToken, not apiKey
  basePath: 'https://api.linkbreakers.com',
});

const linksApi = new LinksApi(config);

// Create a shortened link
const response = await linksApi.linksServiceCreate({
  createLinkRequest: {
    destination: 'https://example.com',
    name: 'My Link',
  },
});

console.log('Short link:', response.link?.shortlink);

Authentication

Important: The Linkbreakers API uses Bearer token authentication. The SDK's Configuration class is designed to only accept the accessToken parameter:

import { Configuration } from 'linkbreakers';

// ✅ CORRECT - Sends "Authorization: Bearer {token}" header
const config = new Configuration({
  accessToken: 'your-workspace-token',
  basePath: 'https://api.linkbreakers.com',
});

// ❌ TypeScript ERROR - apiKey is not a valid parameter
const wrongConfig = new Configuration({
  // @ts-expect-error apiKey is not accepted, use accessToken
  apiKey: 'your-workspace-token',  // TypeScript will show an error here!
  basePath: 'https://api.linkbreakers.com',
});

The SDK prevents you from accidentally using apiKey - TypeScript will show a compile error if you try. This ensures you always use the correct authentication method.

Get your workspace API token from the Linkbreakers dashboard.

Identifying Visitors

Use the VisitorsApi to identify and update visitor profiles. The identify method finds or creates a visitor using their LBID (from tracking) and merges attributes:

import { Configuration, VisitorsApi } from 'linkbreakers';

const config = new Configuration({
  accessToken: 'your_api_key_here',
  basePath: 'https://api.linkbreakers.com',
});

const visitorsApi = new VisitorsApi(config);

// Identify a visitor using their LBID (from tracking cookie/parameter)
const response = await visitorsApi.visitorsServiceIdentify({
  identifyRequest: {
    lbid: 'visitor-lbid-from-tracking',  // Base64 encoded event ID from click/scan
    visitor: {
      data: {
        // System fields (prefixed with "$")
        '$email': '[email protected]',
        '$phone': '+1234567890',
        '$firstName': 'John',
        '$lastName': 'Doe',

        // Custom attributes (no "$" prefix)
        'company': 'Acme Corp',
        'plan': 'premium',
        'signupDate': '2024-01-01'
      }
    },
    setOnce: false  // If true, only sets empty fields (won't overwrite existing)
  }
});

console.log('Created new profile:', response.created);
console.log('Visitor:', response.visitor);

Update an existing visitor by UUID:

// When you have the visitor's UUID (from your database)
const visitor = await visitorsApi.visitorsServiceUpdate({
  id: 'visitor-uuid',
  visitorsServiceUpdateBody: {
    visitor: {
      data: {
        '$email': '[email protected]',
        'plan': 'enterprise'
      }
    }
  }
});

Get visitor details:

const visitor = await visitorsApi.visitorsServiceGet({
  id: 'visitor-uuid',
  include: ['devices', 'events', 'links']  // Optional: include related data
});

List visitors:

const visitors = await visitorsApi.visitorsServiceList({
  pageSize: 50,
  email: '[email protected]',  // Optional filters
  linkId: 'link-uuid',
  search: 'Acme Corp'
});

Full API Support

The SDK provides type-safe methods for all API operations. Method names follow the API's operation IDs (linksServiceCreate, linksServiceList, visitorsServiceIdentify, ...), and each takes a single object holding the path and query parameters plus the request body under its type name (createLinkRequest, linksServiceUpdateBody, ...):

// Get a link by ID
const { link } = await linksApi.linksServiceGet({ id: 'link-id' });

// Update a link
const updated = await linksApi.linksServiceUpdate({
  id: 'link-id',
  linksServiceUpdateBody: {
    name: 'Updated Name',
  },
});

// Delete a link
await linksApi.linksServiceDelete({ id: 'link-id' });

// List links with filtering
const { links, nextPageToken } = await linksApi.linksServiceList({
  pageSize: 50,
  search: 'my-search',
  tags: ['tag1', 'tag2'],
});

Features

• ✅ Full TypeScript support with type definitions
• ✅ Works in Node.js and browsers
• ✅ Auto-generated from OpenAPI specification
• ✅ Automatically updated when API changes

Examples

For complete, runnable code examples, see the examples/ directory:

• identify-visitor.ts - Identify visitors using LBID (most important!)
• update-visitor.ts - Update visitors by UUID
• create-link.ts - Create shortened links with various options
• list-visitors.ts - Query and filter visitors

Each example is complete, well-documented, and ready to run. See examples/README.md for details.

Documentation

For complete API documentation, visit https://docs.linkbreakers.com

Auto-Generated SDK

This SDK is automatically generated from the Linkbreakers OpenAPI specification. When the API is updated, this SDK is automatically regenerated and published.

Current API Version: See OPENAPI_VERSION

Support

• Issues: GitHub Issues
• Documentation: https://docs.linkbreakers.com

License

MIT License - see LICENSE for details.