tly-api 1.0.0 → 1.0.1

package/index.js

@@ -96,9 +96,96 @@ class TlyClient {
 		return response.data;
 	}
 
-	async getStats(shortUrl) {
+	async bulkUpdateLinks(data) {
+		// data: { links, tags, pixels }
+		const response = await this.client.post('/api/v1/link/bulk/update', data);
+		return response.data;
+	}
+
+	async getStats(shortUrl, params = {}) {
 		const response = await this.client.get('/api/v1/link/stats', {
-			params: { short_url: shortUrl },
+			params: {
+				short_url: shortUrl,
+				...params,
+			},
+		});
+		return response.data;
+	}
+
+	// ===== OneLink Management =====
+
+	async getOneLinkStats(shortUrl, params = {}) {
+		const response = await this.client.get('/api/v1/onelink/stats', {
+			params: {
+				short_url: shortUrl,
+				...params,
+			},
+		});
+		return response.data;
+	}
+
+	async deleteOneLinkStats(data) {
+		// data: { short_url }
+		const response = await this.client.delete('/api/v1/onelink/stat', { data });
+		return response.data;
+	}
+
+	async listOneLinks(params = {}) {
+		const response = await this.client.get('/api/v1/onelink/list', { params });
+		return response.data;
+	}
+
+	// ===== UTM Preset Management =====
+
+	async createUtmPreset(data) {
+		// data: { name, source, medium, campaign, content, term }
+		const response = await this.client.post('/api/v1/link/utm-preset', data);
+		return response.data;
+	}
+
+	async listUtmPresets() {
+		const response = await this.client.get('/api/v1/link/utm-preset');
+		return response.data;
+	}
+
+	async getUtmPreset(id) {
+		const response = await this.client.get(`/api/v1/link/utm-preset/${id}`);
+		return response.data;
+	}
+
+	async updateUtmPreset(id, data) {
+		// data: { name, source, medium, campaign, content, term }
+		const response = await this.client.put(`/api/v1/link/utm-preset/${id}`, data);
+		return response.data;
+	}
+
+	async deleteUtmPreset(id) {
+		const response = await this.client.delete(`/api/v1/link/utm-preset/${id}`);
+		return response.data;
+	}
+
+	// ===== QR Code Management =====
+
+	async getQrCode(params = {}, config = {}) {
+		const response = await this.client.get('/api/v1/link/qr-code', {
+			...config,
+			params,
+		});
+		return response.data;
+	}
+
+	async updateQrCode(data) {
+		// data: { short_url, image, background_color, corner_dots_color, dots_color, dots_style, corner_style }
+		const response = await this.client.put('/api/v1/link/qr-code', data);
+		return response.data;
+	}
+
+	async getLinkStats(shortUrl, params = {}) {
+		const response = await this.client.get('/api/v1/link/stats', {
+			params: {
+				short_url: shortUrl,
+				...params,
+			},
 		});
 		return response.data;
 	}

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "tly-api",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"description": "A Node.js client for the T.ly URL Shortener API",
 	"main": "index.js",
 	"scripts": {
-		"test": "echo \"No tests specified\""
+		"test": "node --test"
 	},
 	"keywords": [
 		"t.ly",

package/readme.md

@@ -1,14 +1,17 @@
 # T.LY API Client
 
-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.
+A Node.js client for the [T.LY URL Shortener](https://t.ly/) API. This package provides convenient methods to manage short links, OneLinks, UTM presets, QR codes, tags, and pixels through T.LY's API.
 
 ## Table of Contents
 
 -   [Installation](#installation)
 -   [Getting Started](#getting-started)
 -   [API Reference](#api-reference)
-    -   [Pixel Management](#pixel-management)
     -   [Short Link Management](#short-link-management)
+    -   [OneLink Management](#onelink-management)
+    -   [UTM Preset Management](#utm-preset-management)
+    -   [QR Code Management](#qr-code-management)
+    -   [Pixel Management](#pixel-management)
     -   [Tag Management](#tag-management)
 -   [Example](#example)
 -   [License](#license)
@@ -42,42 +45,6 @@ npm install tly-api
 
 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`:_
-
-    ```js
-    {
-      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`:_
-
-    ```js
-    {
-      id: 123,
-      name: 'Updated Pixel',
-      pixel_id: '987654321',
-      pixel_type: 'facebook'
-    }
-    ```
-
--   **deletePixel(id)**
-    Deletes the pixel by its ID.
-
 ### Short Link Management
 
 -   **createShortLink(data)**
@@ -153,8 +120,71 @@ Below is a summary of the methods available on the `TlyClient` class. For detail
     }
     ```
 
--   **getStats(shortUrl)**
-    Retrieves analytics data for a given short URL.
+-   **bulkUpdateLinks(data)**
+    Updates multiple short links in a single request.
+
+-   **getStats(shortUrl, params)**
+    Retrieves analytics data for a short URL (`/api/v1/link/stats`).
+
+-   **getLinkStats(shortUrl, params)**
+    Alias of `getStats`.
+
+### OneLink Management
+
+-   **getOneLinkStats(shortUrl, params)**
+    Retrieves OneLink analytics (`/api/v1/onelink/stats`).
+    Optional params include `start_date` and `end_date`.
+
+-   **deleteOneLinkStats(data)**
+    Deletes OneLink stats (`/api/v1/onelink/stat`).
+    `data` should include `short_url`.
+
+-   **listOneLinks(params)**
+    Lists OneLinks (`/api/v1/onelink/list`).
+    Optional params include `page`.
+
+### UTM Preset Management
+
+-   **createUtmPreset(data)**
+    Creates a UTM preset.
+
+-   **listUtmPresets()**
+    Lists UTM presets.
+
+-   **getUtmPreset(id)**
+    Retrieves one UTM preset by ID.
+
+-   **updateUtmPreset(id, data)**
+    Updates a UTM preset by ID.
+
+-   **deleteUtmPreset(id)**
+    Deletes a UTM preset by ID.
+
+### QR Code Management
+
+-   **getQrCode(params, config)**
+    Gets a QR code (`/api/v1/link/qr-code`).
+    Use params like `short_url`, `output`, and `format`.
+
+-   **updateQrCode(data)**
+    Updates QR code options (`/api/v1/link/qr-code`).
+
+### Pixel Management
+
+-   **createPixel(data)**
+    Creates a new pixel.
+
+-   **listPixels()**
+    Retrieves a list of all pixels.
+
+-   **getPixel(id)**
+    Retrieves a single pixel by its ID.
+
+-   **updatePixel(id, data)**
+    Updates the pixel's attributes.
+
+-   **deletePixel(id)**
+    Deletes the pixel by its ID.
 
 ### Tag Management
 

package/test/client.test.js

@@ -0,0 +1,181 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const axios = require('axios');
+const TlyClient = require('../index');
+
+function createClientWithRecorder() {
+	const calls = [];
+
+	const fakeHttpClient = {
+		get: async (url, config) => {
+			calls.push({ method: 'get', url, config });
+			return { data: { ok: true, method: 'get', url, config } };
+		},
+		post: async (url, data, config) => {
+			calls.push({ method: 'post', url, data, config });
+			return { data: { ok: true, method: 'post', url, data, config } };
+		},
+		put: async (url, data, config) => {
+			calls.push({ method: 'put', url, data, config });
+			return { data: { ok: true, method: 'put', url, data, config } };
+		},
+		delete: async (url, config) => {
+			calls.push({ method: 'delete', url, config });
+			return { data: { ok: true, method: 'delete', url, config } };
+		},
+	};
+
+	const originalCreate = axios.create;
+	axios.create = () => fakeHttpClient;
+
+	const client = new TlyClient('token');
+	axios.create = originalCreate;
+
+	return { client, calls };
+}
+
+test('constructor requires api token', () => {
+	assert.throws(() => new TlyClient(), /API token is required/);
+});
+
+test('short link methods map to documented endpoints', async () => {
+	const { client, calls } = createClientWithRecorder();
+
+	await client.createShortLink({ long_url: 'https://example.com' });
+	await client.getShortLink('https://t.ly/abc');
+	await client.updateShortLink({ short_url: 'https://t.ly/abc', description: 'updated' });
+	await client.deleteShortLink({ short_url: 'https://t.ly/abc' });
+	await client.expandShortLink({ short_url: 'https://t.ly/abc', password: 'secret' });
+	await client.listShortLinks({ search: 'example', page: 2 });
+	await client.bulkShortenLinks({ links: [{ LongUrl: 'https://example.com' }] });
+	await client.bulkUpdateLinks({ links: [{ ShortURL: 'https://t.ly/abc' }] });
+	await client.getStats('https://t.ly/abc', { start_date: '2024-01-01', end_date: '2024-01-31' });
+	await client.getLinkStats('https://t.ly/xyz');
+
+	assert.deepEqual(calls.map((call) => `${call.method.toUpperCase()} ${call.url}`), [
+		'POST /api/v1/link/shorten',
+		'GET /api/v1/link',
+		'PUT /api/v1/link',
+		'DELETE /api/v1/link',
+		'POST /api/v1/link/expand',
+		'GET /api/v1/link/list',
+		'POST /api/v1/link/bulk',
+		'POST /api/v1/link/bulk/update',
+		'GET /api/v1/link/stats',
+		'GET /api/v1/link/stats',
+	]);
+
+	assert.deepEqual(calls[1].config, {
+		params: { short_url: 'https://t.ly/abc' },
+	});
+	assert.deepEqual(calls[3].config, {
+		data: { short_url: 'https://t.ly/abc' },
+	});
+	assert.deepEqual(calls[8].config, {
+		params: {
+			short_url: 'https://t.ly/abc',
+			start_date: '2024-01-01',
+			end_date: '2024-01-31',
+		},
+	});
+	assert.deepEqual(calls[9].config, {
+		params: {
+			short_url: 'https://t.ly/xyz',
+		},
+	});
+});
+
+test('tag and pixel methods map to documented endpoints', async () => {
+	const { client, calls } = createClientWithRecorder();
+
+	await client.listTags();
+	await client.createTag({ tag: 'news' });
+	await client.getTag(123);
+	await client.updateTag(123, { tag: 'updates' });
+	await client.deleteTag(123);
+
+	await client.createPixel({ name: 'pixel', pixel_id: 'abc', pixel_type: 'facebook' });
+	await client.listPixels();
+	await client.getPixel(55);
+	await client.updatePixel(55, { name: 'pixel2', pixel_id: 'xyz', pixel_type: 'googleTagManager' });
+	await client.deletePixel(55);
+
+	assert.deepEqual(calls.map((call) => `${call.method.toUpperCase()} ${call.url}`), [
+		'GET /api/v1/link/tag',
+		'POST /api/v1/link/tag',
+		'GET /api/v1/link/tag/123',
+		'PUT /api/v1/link/tag/123',
+		'DELETE /api/v1/link/tag/123',
+		'POST /api/v1/link/pixel',
+		'GET /api/v1/link/pixel',
+		'GET /api/v1/link/pixel/55',
+		'PUT /api/v1/link/pixel/55',
+		'DELETE /api/v1/link/pixel/55',
+	]);
+});
+
+test('onelink, utm preset, and qr methods map to documented endpoints', async () => {
+	const { client, calls } = createClientWithRecorder();
+
+	await client.getOneLinkStats('https://t.ly/one', { start_date: '2024-06-01', end_date: '2024-06-08' });
+	await client.deleteOneLinkStats({ short_url: 'https://t.ly/one' });
+	await client.listOneLinks({ page: 3 });
+
+	await client.createUtmPreset({
+		name: 'Newsletter Launch',
+		source: 'newsletter',
+		medium: 'email',
+		campaign: 'fall_launch',
+		content: 'hero-cta',
+		term: 'running-shoes',
+	});
+	await client.listUtmPresets();
+	await client.getUtmPreset(10);
+	await client.updateUtmPreset(10, { name: 'Updated Preset' });
+	await client.deleteUtmPreset(10);
+
+	await client.getQrCode({
+		short_url: 'https://t.ly/c55j',
+		output: 'base64',
+		format: 'eps',
+	});
+	await client.updateQrCode({
+		short_url: 'https://t.ly/c55j',
+		background_color: '#ffffff',
+		dots_color: '#000000',
+	});
+
+	assert.deepEqual(calls.map((call) => `${call.method.toUpperCase()} ${call.url}`), [
+		'GET /api/v1/onelink/stats',
+		'DELETE /api/v1/onelink/stat',
+		'GET /api/v1/onelink/list',
+		'POST /api/v1/link/utm-preset',
+		'GET /api/v1/link/utm-preset',
+		'GET /api/v1/link/utm-preset/10',
+		'PUT /api/v1/link/utm-preset/10',
+		'DELETE /api/v1/link/utm-preset/10',
+		'GET /api/v1/link/qr-code',
+		'PUT /api/v1/link/qr-code',
+	]);
+
+	assert.deepEqual(calls[0].config, {
+		params: {
+			short_url: 'https://t.ly/one',
+			start_date: '2024-06-01',
+			end_date: '2024-06-08',
+		},
+	});
+	assert.deepEqual(calls[1].config, {
+		data: { short_url: 'https://t.ly/one' },
+	});
+	assert.deepEqual(calls[2].config, {
+		params: { page: 3 },
+	});
+	assert.deepEqual(calls[8].config, {
+		params: {
+			short_url: 'https://t.ly/c55j',
+			output: 'base64',
+			format: 'eps',
+		},
+	});
+});