tly-api

T.LY API Client

A Node.js client for the T.LY URL Shortener API. This package provides convenient methods to manage short links, tags, and pixels through T.LY's API.

Table of Contents

• Installation
• Getting Started
• API Reference
  • Pixel Management
  • Short Link Management
  • Tag Management
• Example
• License

Installation

Install the package via npm:

npm install tly-api

Getting Started

• Obtain an API Token: Sign up or log in to T.LY and retrieve your API token from the T.LY dashboard.

• Initialize the Client:

  const TlyClient = require('tly-api');
  
  // Replace 'YOUR_API_TOKEN' with your actual T.LY API token.
  const tly = new TlyClient('YOUR_API_TOKEN');
  

• Use the Methods: You can now call any of the available methods (short link creation, pixel management, tag management, etc.) on the tly instance.

API Reference

Below is a summary of the methods available on the TlyClient class. For detailed parameter structures, refer to the inline code comments.

Pixel Management

• createPixel(data) Creates a new pixel. Example data:

  {
    name: 'My Facebook Pixel',
    pixel_id: '123456789',
    pixel_type: 'facebook'
  }
  

• listPixels() Retrieves a list of all pixels.

• getPixel(id) Retrieves a single pixel by its ID.

• updatePixel(id, data) Updates the pixel's attributes. Example data:

  {
    id: 123,
    name: 'Updated Pixel',
    pixel_id: '987654321',
    pixel_type: 'facebook'
  }
  

• deletePixel(id) Deletes the pixel by its ID.

Short Link Management

• createShortLink(data) Creates a new short link. Example data:

  {
    long_url: 'https://example.com',
    short_id: 'customalias',
    domain: 't.ly',
    expire_at_datetime: '2025-12-31T23:59:59Z',
    expire_at_views: 1000,
    description: 'My short link',
    public_stats: false,
    password: 'optionalPassword',
    tags: [1, 2],
    pixels: [101, 102],
    meta: { 'title': 'Custom Title' }
  }
  

• getShortLink(shortUrl) Retrieves a short link by its short URL (e.g., t.ly/alias).

• updateShortLink(data) Updates an existing short link. Important: data should include short_url along with any fields to update.

• deleteShortLink(data) Deletes a short link. Important: data must include the short_url you wish to delete.

• expandShortLink(data) Retrieves the long URL behind a short URL. Example data:

  {
    short_url: 't.ly/alias',
    password: 'ifProtected'
  }
  

• listShortLinks(params) Retrieves a paginated list of short links. Example params:

  {
    search: 'example',
    tag_ids: [1],
    pixel_ids: [101],
    start_date: '2025-01-01',
    end_date: '2025-01-31',
    domains: ['t.ly']
  }
  

• bulkShortenLinks(data) Shortens multiple links at once. Example data:

  {
    domain: 't.ly',
    links: [
      { long_url: 'https://site1.com' },
      { long_url: 'https://site2.com' }
    ],
    tags: [1, 2],
    pixels: [101, 102]
  }
  

• getStats(shortUrl) Retrieves analytics data for a given short URL.

Tag Management

• listTags() Retrieves a list of all tags.

• createTag(data) Creates a new tag. Example data:

  {
  	tag: 'Marketing';
  }
  

• getTag(id) Retrieves a single tag by its ID.

• updateTag(id, data) Updates the tag’s attributes. Example data:

  {
  	tag: 'New Tag Name';
  }
  

• deleteTag(id) Deletes the tag by its ID.

Example

Below is a simple usage example demonstrating how to create and retrieve a short link:

const TlyClient = require('tly-api');

// Replace 'YOUR_API_TOKEN' with your actual T.LY API token.
const tly = new TlyClient('YOUR_API_TOKEN');

async function runExample() {
	try {
		// Create a new short link
		const createdLink = await tly.createShortLink({
			long_url: 'https://www.example.com',
			description: 'Example Link',
		});
		console.log('Created Short Link:', createdLink);

		// Retrieve the details of the created short link
		const shortUrl = createdLink.short_url;
		const linkInfo = await tly.getShortLink(shortUrl);
		console.log('Retrieved Link Info:', linkInfo);
	} catch (error) {
		console.error('Error:', error.response ? error.response.data : error.message);
	}
}

runExample();

License

This package is licensed under the MIT License.