furtrack-api 1.0.1

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/workflows/node.js.yml

@@ -0,0 +1,31 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Node.js CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 blumlaut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# furtrack-api
+
+An unofficial Node.js package for accessing the Furtrack API.
+
+
+## Features
+
+- Fetch posts, users, tags, albums, and thumbnails from Furtrack
+- Supports API key authentication
+- Customizable HTTP headers (e.g., User-Agent)
+- Tag parsing and filtering utilities
+
+## Installation
+
+```sh
+npm install furtrack-api
+```
+
+## Usage
+
+```js
+const FurtrackAPI = require('furtrack-api');
+
+// Basic usage
+const api = new FurtrackAPI();
+
+// With API key and custom headers
+const apiWithAuth = new FurtrackAPI({
+	apiKey: 'YOUR_API_KEY',
+	headers: {
+	'User-Agent': 'MyCustomAgent/1.0',
+	'X-Custom-Header': 'foobar'
+	}
+});
+
+// Set or update API key later
+api.setApiKey('NEW_API_KEY');
+
+// Set or merge additional headers
+api.setHeaders({
+	'User-Agent': 'AnotherAgent/2.0'
+});
+
+// Fetch a user
+api.getUser('username').then(user => {
+	console.log(user);
+});
+
+api.getPost(1337).then(post => {
+	console.log(post);
+})
+
+// fetch a user's posts
+api.getPostsByUser('username').then(posts => {
+	console.log(posts);
+});
+
+// Fetch posts by tag with pagination
+api.getPostsByTag('1:Fluffy', 2).then(posts => {
+	console.log(posts);
+});
+
+// Fetch a user's liked posts
+api.getLikes('username').then(posts => {
+	console.log(posts);
+})
+
+// Fetch a post's thumbnail URL
+api.getThumbnail(12345).then(url => {
+	console.log(url);
+});
+
+// Fetch a user's album.
+api.getAlbum('username', 'albumid').then(album => {
+	console.log(album)
+})
+
+```
+
+Functions which return a list of arrays additional support a page argument, FurTrack generally paginates albums longer than 200 images, by default only the first page is retrieved.
+
+## Tag Utilities
+
+```js
+// Parse a tag string
+const parsed = api.parseTag('1:Fluffy');
+// => { type: 'character', value: 'Fluffy' }
+
+// Filter tags by type
+const tags = [{ tagName: '1:Alpha' }, { tagName: '2:Beta' }];
+const characters = FurtrackAPI.getTagsByType(tags, FurtrackAPI.TagTypes.Character);
+// => ['Alpha']
+```
+
+---
+
+MIT License © 2025 blumlaut

package/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  testEnvironment: 'node',
+  collectCoverage: true,
+  coverageDirectory: 'coverage',
+  verbose: true,
+};

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "furtrack-api",
+  "version": "1.0.1",
+  "description": "An inofficial package for accessing the Furtrack API.",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "furtrack"
+  ],
+  "author": "blumlaut",
+  "license": "MIT",
+  "dependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,207 @@
+const https = require('https');
+
+
+/**
+ * FurtrackAPI provides methods to interact with the Furtrack API, including fetching posts, users, tags, albums, and thumbnails.
+ * 
+ * @class
+ * @param {Object} [options] - Configuration options.
+ * @param {string} [options.apiKey] - Optional API key for authenticated requests.
+ * @param {Object} [options.headers] - Additional headers to include in requests.
+ * 
+ * @property {string} apiKey - The API key used for authentication.
+ * @property {string} baseUrl - The base URL for the Furtrack API.
+ * @property {Object} agent - HTTPS agent for custom TLS settings.
+ * @property {Object} defaultHeaders - Default headers for all requests.
+ * 
+ * @static
+ * @property {Object} TagTypes - Enum for tag types.
+ * @property {Object} tagTypePrefixes - Mapping of tag prefixes to tag types.
+ * 
+ * @method setApiKey Sets the API key for authentication.
+ * @param {string} apiKey - The API key to set.
+ * 
+ * @method setHeaders Sets additional headers for requests.
+ * @param {Object} headers - Headers to merge with the default headers.
+ * 
+ * @method fetchJSON Fetches JSON data from a given API path.
+ * @param {string} path - The API endpoint path.
+ * @param {Object} [options] - Additional fetch options.
+ * @returns {Promise<Object>} The parsed JSON response.
+ * 
+ * @method getTag Fetches information about a specific tag.
+ * @param {string} tag - The tag to fetch.
+ * @returns {Promise<Object>} Tag information.
+ * 
+ * @method getUser Fetches information about a specific user.
+ * @param {string} username - The username to fetch.
+ * @returns {Promise<Object>} User information.
+ * 
+ * @method getPost Fetches information about a specific post.
+ * @param {string|number} postId - The post ID to fetch.
+ * @returns {Promise<Object>} Post information.
+ * 
+ * @method getPostsByTag Fetches posts associated with a tag, with pagination.
+ * @param {string} tag - The tag to search for.
+ * @param {number} [page=0] - The page number for pagination.
+ * @returns {Promise<Array>} Array of posts.
+ * 
+ * @method getPostsByUser Fetches posts by a specific user, with pagination.
+ * @param {string} username - The username whose posts to fetch.
+ * @param {number} [page=0] - The page number for pagination.
+ * @returns {Promise<Array>} Array of posts.
+ * 
+ * @method getLikes Fetches posts liked by a user, with pagination.
+ * @param {string} username - The username whose liked posts to fetch.
+ * @param {number} [page=0] - The page number for pagination.
+ * @returns {Promise<Array>} Array of liked posts.
+ * 
+ * @method getThumbnail Constructs the thumbnail URL for a post.
+ * @param {string|number} postId - The post ID.
+ * @returns {Promise<string>} The thumbnail URL.
+ * 
+ * @method getAlbum Fetches information about a user's album.
+ * @param {string} username - The username.
+ * @param {string|number} albumId - The album ID.
+ * @returns {Promise<Object>} Album information.
+ * 
+ * @method parseTag Parses a tag string into its type and value.
+ * @param {string} tagString - The tag string to parse.
+ * @returns {Object} An object with `type` and `value` properties.
+ * 
+ * @static
+ * @method getTagsByType Filters and extracts tag values by type.
+ * @param {Array} tags - Array of tag objects with a `tagName` property.
+ * @param {string} type - The tag type to filter by.
+ * @returns {Array<string>} Array of tag values matching the type.
+ */
+
+class FurtrackAPI {
+	constructor({ apiKey = undefined, headers = {} } = {}) {
+		this.apiKey = apiKey;
+		this.baseUrl = 'https://solar.furtrack.com';
+		this.agent = new https.Agent({
+			rejectUnauthorized: false,
+			ciphers: 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384',
+			honorCipherOrder: true,
+			minVersion: 'TLSv1.2',
+			maxVersion: 'TLSv1.3'
+		});
+
+		this.defaultHeaders = {
+			"User-Agent": `furtrack-api/${require('../package.json').version} (https://github.com/blumlaut/furtrack-api) Mozilla/5.0 (compatible; FurtrackAPI/${require('../package.json').version}`,
+			"Accept": "application/json, text/plain, */*",
+			"Referer": "https://www.furtrack.com/",
+			"Origin": "https://www.furtrack.com",
+			"Accept-Language": "en-US,en;q=0.5",
+			...headers
+		};
+
+		if (this.apiKey) {
+			this.defaultHeaders['Authorization'] = `Bearer ${this.apiKey}`;
+		}
+	}
+
+	static TagTypes = {
+		Character: 'character',
+		Maker: 'maker',
+		Photographer: 'photographer',
+		Species: 'species',
+		Event: 'event',
+		General: 'general'
+	};
+
+	static tagTypePrefixes = {
+		'1:': this.TagTypes.Character,
+		'2:': this.TagTypes.Maker,
+		'3:': this.TagTypes.Photographer,
+		'5:': this.TagTypes.Event,
+		'6': this.TagTypes.Species,
+
+	};
+
+	setApiKey(apiKey) {
+		this.apiKey = apiKey;
+		this.defaultHeaders['Authorization'] = `Bearer ${apiKey}`;
+	}
+
+	setHeaders(headers) {
+		this.defaultHeaders = { ...this.defaultHeaders, ...headers };
+	}
+
+	async fetchJSON(path, options = {}) {
+		const url = `${this.baseUrl}${path}`;
+		const fetchOptions = {
+			method: 'GET',
+			agent: this.agent,
+			headers: this.defaultHeaders,
+			...options
+		};
+		const res = await fetch(url, fetchOptions);
+		if (!res.ok) throw new Error(`HTTP error ${res.status}`);
+		return res.json();
+	}
+
+	getTag(tag) {
+		return this.fetchJSON(`/get/index/${encodeURIComponent(tag)}`);
+	}
+
+	getUser(username) {
+		return this.fetchJSON(`/get/u/${encodeURIComponent(username)}`);
+	}
+
+	getPost(postId) {
+		return this.fetchJSON(`/view/post/${encodeURIComponent(postId)}`);
+	}
+
+	async getPostsByTag(tag, page = 0) {
+		const response = await this.fetchJSON(`/get/tag/${encodeURIComponent(tag)}${page > 0 ? `/${page}` : ''}`);
+		return response.posts || [];
+	}
+
+	async getPostsByUser(username, page = 0) {
+		const response = await this.fetchJSON(`/view/album/${encodeURIComponent(username)}/3${page > 0 ? `/${page}` : ''}`);
+		return response.posts || [];
+	}
+
+	async getLikes(username, page = 0) {
+		const response = await this.fetchJSON(`/view/album/${encodeURIComponent(username)}/o${page > 0 ? `/${page}` : ''}`);
+		return response.posts || [];
+	}
+	
+	async getThumbnail(postId) {
+		const postData = await this.getPost(postId);
+		if (!postData.submitUserId || !postData.id || !postData.metaFingerprint || !postData.metaFiletype) {
+			throw new Error('Missing required fields in postData for constructing thumbnail URL');
+		}
+		return `https://orca2.furtrack.com/gallery/${postData.submitUserId}/${postData.id}-${postData.metaFingerprint}.${postData.metaFiletype}`;
+	}
+
+	getAlbum(username, albumId, page = 0) {
+		return this.fetchJSON(`/view/album/${encodeURIComponent(username)}/${encodeURIComponent(albumId)}${page > 0 ? `/${page}` : ''}`);
+	}
+
+	parseTag(tagString) {
+		return FurtrackAPI.parseTag(tagString);
+	}
+
+	static parseTag(tagString) {
+		for (const [prefix, type] of Object.entries(this.tagTypePrefixes)) {
+			if (tagString.startsWith(prefix)) {
+				return { type, value: tagString.slice(prefix.length) };
+			}
+		}
+		return { type: this.TagTypes.General, value: tagString };
+	}
+
+
+	static getTagsByType(tags, type) {
+		return tags
+			.map(tag => this.parseTag(tag.tagName))
+			.filter(parsed => parsed.type === type)
+			.map(parsed => parsed.value);
+	}
+
+}
+
+module.exports = FurtrackAPI;

package/src/index.test.js

@@ -0,0 +1,79 @@
+const { test, expect, describe, beforeEach } = require('@jest/globals');
+const FurtrackAPI = require('./index');
+
+describe('FurtrackAPI', () => {
+	let api;
+
+	beforeEach(() => {
+		api = new FurtrackAPI();
+	});
+
+	test('constructor sets default values', () => {
+		expect(api.apiKey).toBeUndefined();
+		expect(api.baseUrl).toBe('https://solar.furtrack.com');
+		expect(api.defaultHeaders['User-Agent']).toMatch(/furtrack-api/);
+	});
+
+	test('constructor sets apiKey and Authorization header', () => {
+		const api2 = new FurtrackAPI({ apiKey: 'abc123' });
+		expect(api2.apiKey).toBe('abc123');
+		expect(api2.defaultHeaders.Authorization).toBe('Bearer abc123');
+	});
+
+	test('setApiKey updates apiKey and Authorization header', () => {
+		api.setApiKey('newkey');
+		expect(api.apiKey).toBe('newkey');
+		expect(api.defaultHeaders.Authorization).toBe('Bearer newkey');
+	});
+
+	test('setHeaders merges headers', () => {
+		api.setHeaders({ 'X-Test': 'foo' });
+		expect(api.defaultHeaders['X-Test']).toBe('foo');
+		expect(api.defaultHeaders['User-Agent']).toBeDefined();
+	});
+
+	describe('parseTag', () => {
+		test('parses character tag', () => {
+			const result = api.parseTag('1:Fluffy');
+			expect(result).toEqual({ type: FurtrackAPI.TagTypes.Character, value: 'Fluffy' });
+		});
+		test('parses maker tag', () => {
+			const result = api.parseTag('2:MakerName');
+			expect(result).toEqual({ type: FurtrackAPI.TagTypes.Maker, value: 'MakerName' });
+		});
+		test('parses photographer tag', () => {
+			const result = api.parseTag('3:PhotoGuy');
+			expect(result).toEqual({ type: FurtrackAPI.TagTypes.Photographer, value: 'PhotoGuy' });
+		});
+		test('parses event tag', () => {
+			const result = api.parseTag('5:SomeEvent');
+			expect(result).toEqual({ type: FurtrackAPI.TagTypes.Event, value: 'SomeEvent' });
+		});
+		test('parses species tag', () => {
+			const result = api.parseTag('6Wolf');
+			expect(result).toEqual({ type: FurtrackAPI.TagTypes.Species, value: 'Wolf' });
+		});
+		test('parses general tag', () => {
+			const result = api.parseTag('randomtag');
+			expect(result).toEqual({ type: FurtrackAPI.TagTypes.General, value: 'randomtag' });
+		});
+	});
+
+	describe('getTagsByType', () => {
+		test('filters and extracts tag values by type', () => {
+			const tags = [
+				{ tagName: '1:Alpha' },
+				{ tagName: '2:Beta' },
+				{ tagName: '1:Gamma' },
+				{ tagName: 'random' }
+			];
+			const result = FurtrackAPI.getTagsByType(tags, FurtrackAPI.TagTypes.Character);
+			expect(result).toEqual(['Alpha', 'Gamma']);
+		});
+		test('returns empty array if no tags match', () => {
+			const tags = [{ tagName: '2:Beta' }];
+			const result = FurtrackAPI.getTagsByType(tags, FurtrackAPI.TagTypes.Event);
+			expect(result).toEqual([]);
+		});
+	});
+});