├── package.json ├── index.js └── readme.md /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "tly-api", 3 | "version": "1.0.0", 4 | "description": "A Node.js client for the T.ly URL Shortener API", 5 | "main": "index.js", 6 | "scripts": { 7 | "test": "echo \"No tests specified\"" 8 | }, 9 | "keywords": [ 10 | "t.ly", 11 | "url shortener", 12 | "link shortener", 13 | "api", 14 | "client" 15 | ], 16 | "author": "Your Name", 17 | "license": "MIT", 18 | "dependencies": { 19 | "axios": "^1.4.0" 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | const axios = require('axios'); 2 | 3 | class TlyClient { 4 | /** 5 | * Creates an instance of TlyClient. 6 | * @param {string} apiToken - Your T.ly API token. 7 | * @param {string} [baseURL='https://api.t.ly'] - The base URL for the API. 8 | */ 9 | constructor(apiToken, baseURL = 'https://api.t.ly') { 10 | if (!apiToken) { 11 | throw new Error('API token is required'); 12 | } 13 | this.apiToken = apiToken; 14 | this.client = axios.create({ 15 | baseURL, 16 | headers: { 17 | Authorization: `Bearer ${apiToken}`, 18 | 'Content-Type': 'application/json', 19 | Accept: 'application/json', 20 | }, 21 | }); 22 | } 23 | 24 | // ===== Pixel Management ===== 25 | 26 | async createPixel(data) { 27 | // data: { name, pixel_id, pixel_type } 28 | const response = await this.client.post('/api/v1/link/pixel', data); 29 | return response.data; 30 | } 31 | 32 | async listPixels() { 33 | const response = await this.client.get('/api/v1/link/pixel'); 34 | return response.data; 35 | } 36 | 37 | async getPixel(id) { 38 | const response = await this.client.get(`/api/v1/link/pixel/${id}`); 39 | return response.data; 40 | } 41 | 42 | async updatePixel(id, data) { 43 | // data: { id, name, pixel_id, pixel_type } 44 | const response = await this.client.put(`/api/v1/link/pixel/${id}`, data); 45 | return response.data; 46 | } 47 | 48 | async deletePixel(id) { 49 | const response = await this.client.delete(`/api/v1/link/pixel/${id}`); 50 | return response.data; 51 | } 52 | 53 | // ===== Short Link Management ===== 54 | 55 | async createShortLink(data) { 56 | // data: { long_url, short_id, domain, expire_at_datetime, expire_at_views, description, public_stats, password, tags, pixels, meta } 57 | const response = await this.client.post('/api/v1/link/shorten', data); 58 | return response.data; 59 | } 60 | 61 | async getShortLink(shortUrl) { 62 | const response = await this.client.get('/api/v1/link', { 63 | params: { short_url: shortUrl }, 64 | }); 65 | return response.data; 66 | } 67 | 68 | async updateShortLink(data) { 69 | // data should contain short_url along with the fields to update. 70 | const response = await this.client.put('/api/v1/link', data); 71 | return response.data; 72 | } 73 | 74 | async deleteShortLink(data) { 75 | // data: { short_url } 76 | // axios.delete accepts a config object with data when the API requires a request body. 77 | const response = await this.client.delete('/api/v1/link', { data }); 78 | return response.data; 79 | } 80 | 81 | async expandShortLink(data) { 82 | // data: { short_url, password (optional) } 83 | const response = await this.client.post('/api/v1/link/expand', data); 84 | return response.data; 85 | } 86 | 87 | async listShortLinks(params = {}) { 88 | // params: { search, tag_ids, pixel_ids, start_date, end_date, domains } 89 | const response = await this.client.get('/api/v1/link/list', { params }); 90 | return response.data; 91 | } 92 | 93 | async bulkShortenLinks(data) { 94 | // data: { domain, links, tags, pixels } 95 | const response = await this.client.post('/api/v1/link/bulk', data); 96 | return response.data; 97 | } 98 | 99 | async getStats(shortUrl) { 100 | const response = await this.client.get('/api/v1/link/stats', { 101 | params: { short_url: shortUrl }, 102 | }); 103 | return response.data; 104 | } 105 | 106 | // ===== Tag Management ===== 107 | 108 | async listTags() { 109 | const response = await this.client.get('/api/v1/link/tag'); 110 | return response.data; 111 | } 112 | 113 | async createTag(data) { 114 | // data: { tag } 115 | const response = await this.client.post('/api/v1/link/tag', data); 116 | return response.data; 117 | } 118 | 119 | async getTag(id) { 120 | const response = await this.client.get(`/api/v1/link/tag/${id}`); 121 | return response.data; 122 | } 123 | 124 | async updateTag(id, data) { 125 | // data: { tag } 126 | const response = await this.client.put(`/api/v1/link/tag/${id}`, data); 127 | return response.data; 128 | } 129 | 130 | async deleteTag(id) { 131 | const response = await this.client.delete(`/api/v1/link/tag/${id}`); 132 | return response.data; 133 | } 134 | } 135 | 136 | module.exports = TlyClient; 137 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # T.LY API Client 2 | 3 | A Node.js client for the [T.LY URL Shortener](https://t.ly/) API. This package provides convenient methods to manage short links, tags, and pixels through T.LY's API. 4 | 5 | ## Table of Contents 6 | 7 | - [Installation](#installation) 8 | - [Getting Started](#getting-started) 9 | - [API Reference](#api-reference) 10 | - [Pixel Management](#pixel-management) 11 | - [Short Link Management](#short-link-management) 12 | - [Tag Management](#tag-management) 13 | - [Example](#example) 14 | - [License](#license) 15 | 16 | ## Installation 17 | 18 | Install the package via [npm](https://www.npmjs.com/): 19 | 20 | ``` 21 | 22 | npm install tly-api 23 | 24 | ``` 25 | 26 | ## Getting Started 27 | 28 | 1. **Obtain an API Token**: Sign up or log in to [T.LY](https://t.ly/settings#/api) and retrieve your API token from the T.LY dashboard. 29 | 30 | 2. **Initialize the Client**: 31 | 32 | ```js 33 | const TlyClient = require('tly-api'); 34 | 35 | // Replace 'YOUR_API_TOKEN' with your actual T.LY API token. 36 | const tly = new TlyClient('YOUR_API_TOKEN'); 37 | ``` 38 | 39 | 3. **Use the Methods**: You can now call any of the available methods (short link creation, pixel management, tag management, etc.) on the `tly` instance. 40 | 41 | ## API Reference 42 | 43 | Below is a summary of the methods available on the `TlyClient` class. For detailed parameter structures, refer to the inline code comments. 44 | 45 | ### Pixel Management 46 | 47 | - **createPixel(data)** 48 | Creates a new pixel. 49 | _Example `data`:_ 50 | 51 | ```js 52 | { 53 | name: 'My Facebook Pixel', 54 | pixel_id: '123456789', 55 | pixel_type: 'facebook' 56 | } 57 | ``` 58 | 59 | - **listPixels()** 60 | Retrieves a list of all pixels. 61 | 62 | - **getPixel(id)** 63 | Retrieves a single pixel by its ID. 64 | 65 | - **updatePixel(id, data)** 66 | Updates the pixel's attributes. 67 | _Example `data`:_ 68 | 69 | ```js 70 | { 71 | id: 123, 72 | name: 'Updated Pixel', 73 | pixel_id: '987654321', 74 | pixel_type: 'facebook' 75 | } 76 | ``` 77 | 78 | - **deletePixel(id)** 79 | Deletes the pixel by its ID. 80 | 81 | ### Short Link Management 82 | 83 | - **createShortLink(data)** 84 | Creates a new short link. 85 | _Example `data`:_ 86 | 87 | ```js 88 | { 89 | long_url: 'https://example.com', 90 | short_id: 'customalias', 91 | domain: 't.ly', 92 | expire_at_datetime: '2025-12-31T23:59:59Z', 93 | expire_at_views: 1000, 94 | description: 'My short link', 95 | public_stats: false, 96 | password: 'optionalPassword', 97 | tags: [1, 2], 98 | pixels: [101, 102], 99 | meta: { 'title': 'Custom Title' } 100 | } 101 | ``` 102 | 103 | - **getShortLink(shortUrl)** 104 | Retrieves a short link by its short URL (e.g., `t.ly/alias`). 105 | 106 | - **updateShortLink(data)** 107 | Updates an existing short link. 108 | _Important:_ `data` should include `short_url` along with any fields to update. 109 | 110 | - **deleteShortLink(data)** 111 | Deletes a short link. 112 | _Important:_ `data` must include the `short_url` you wish to delete. 113 | 114 | - **expandShortLink(data)** 115 | Retrieves the long URL behind a short URL. 116 | _Example `data`:_ 117 | 118 | ```js 119 | { 120 | short_url: 't.ly/alias', 121 | password: 'ifProtected' 122 | } 123 | ``` 124 | 125 | - **listShortLinks(params)** 126 | Retrieves a paginated list of short links. 127 | _Example `params`:_ 128 | 129 | ```js 130 | { 131 | search: 'example', 132 | tag_ids: [1], 133 | pixel_ids: [101], 134 | start_date: '2025-01-01', 135 | end_date: '2025-01-31', 136 | domains: ['t.ly'] 137 | } 138 | ``` 139 | 140 | - **bulkShortenLinks(data)** 141 | Shortens multiple links at once. 142 | _Example `data`:_ 143 | 144 | ```js 145 | { 146 | domain: 't.ly', 147 | links: [ 148 | { long_url: 'https://site1.com' }, 149 | { long_url: 'https://site2.com' } 150 | ], 151 | tags: [1, 2], 152 | pixels: [101, 102] 153 | } 154 | ``` 155 | 156 | - **getStats(shortUrl)** 157 | Retrieves analytics data for a given short URL. 158 | 159 | ### Tag Management 160 | 161 | - **listTags()** 162 | Retrieves a list of all tags. 163 | 164 | - **createTag(data)** 165 | Creates a new tag. 166 | _Example `data`:_ 167 | 168 | ```js 169 | { 170 | tag: 'Marketing'; 171 | } 172 | ``` 173 | 174 | - **getTag(id)** 175 | Retrieves a single tag by its ID. 176 | 177 | - **updateTag(id, data)** 178 | Updates the tag’s attributes. 179 | _Example `data`:_ 180 | 181 | ```js 182 | { 183 | tag: 'New Tag Name'; 184 | } 185 | ``` 186 | 187 | - **deleteTag(id)** 188 | Deletes the tag by its ID. 189 | 190 | ## Example 191 | 192 | Below is a simple usage example demonstrating how to create and retrieve a short link: 193 | 194 | ```js 195 | const TlyClient = require('tly-api'); 196 | 197 | // Replace 'YOUR_API_TOKEN' with your actual T.LY API token. 198 | const tly = new TlyClient('YOUR_API_TOKEN'); 199 | 200 | async function runExample() { 201 | try { 202 | // Create a new short link 203 | const createdLink = await tly.createShortLink({ 204 | long_url: 'https://www.example.com', 205 | description: 'Example Link', 206 | }); 207 | console.log('Created Short Link:', createdLink); 208 | 209 | // Retrieve the details of the created short link 210 | const shortUrl = createdLink.short_url; 211 | const linkInfo = await tly.getShortLink(shortUrl); 212 | console.log('Retrieved Link Info:', linkInfo); 213 | } catch (error) { 214 | console.error('Error:', error.response ? error.response.data : error.message); 215 | } 216 | } 217 | 218 | runExample(); 219 | ``` 220 | 221 | ## License 222 | 223 | This package is licensed under the MIT License. 224 | --------------------------------------------------------------------------------