From 1bf63c887a0988b1a82dc01f042b2f4009b8279d Mon Sep 17 00:00:00 2001
From:  <>
Date: Fri, 1 Nov 2024 01:19:27 +0000
Subject: [PATCH] Deployed 5a4215d with MkDocs version: 1.6.1

---
 faq/index.html           |   6 +++---
 search/search_index.json |   2 +-
 sitemap.xml.gz           | Bin 127 -> 127 bytes
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/faq/index.html b/faq/index.html
index 0d5b7d9..d5852a2 100644
--- a/faq/index.html
+++ b/faq/index.html
@@ -851,12 +851,12 @@ <h3 id="which-commands-can-i-use">Which commands can I use?<a class="headerlink"
 <li><strong><code>/gt renewcache</code></strong> (3) – Manually renews the cache.</li>
 <li><strong><code>/gt link</code></strong> (4) – Links your Minecraft account to external connections.<ul>
 <li><strong><code>discord</code></strong> - Begins the process to link your Minecraft account with your Discord. Join our <a href="https://globaltags.xyz/discord" target="_blank">Discord Server</a> to complete the connection.</li>
-<li><strong><code>email &lt;email&gt;</code></strong> - Adds an email to receive account-related updates. This is not a newsletter.</li>
+<li><strong><code>email &lt;address&gt;</code></strong> - Adds an email to receive account-related updates. This is not a newsletter.</li>
 </ul>
 </li>
 <li><strong><code>/gt unlink</code></strong> (5) – Removes external connections from your Minecraft account.<ul>
 <li><strong><code>discord</code></strong> - Unlinks your Minecraft account from Discord.</li>
-<li><strong><code>email &lt;email&gt;</code></strong> - Removes your email from the account.</li>
+<li><strong><code>email</code></strong> - Removes your email from the account.</li>
 </ul>
 </li>
 <li><strong><code>/gt verify</code></strong> (6) - Verifies specific connections.<ul>
@@ -977,7 +977,7 @@ <h3 id="why-cant-i-include-certain-words-in-my-tag">Why can't I include certain
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">October 6, 2024</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">November 1, 2024</span>
   </span>
 
     
diff --git a/search/search_index.json b/search/search_index.json
index 891ee73..48564f0 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to GlobalTags","text":"We're looking for developers! <p>We're currently working on a Fabric version of GlobalTags. If you have good fabric and mixin knowledge and you want to contribute, feel free to create a ticket on our Discord Server!</p> <p>GlobalTags is an API designed to enhance player experiences by allowing users to create custom tags visible to everyone using the addon. This documentation will guide you through integrating, customizing, and extending GlobalTags for your project.</p>"},{"location":"#what-is-globaltags","title":"What is GlobalTags?","text":"<p>GlobalTags enables players to create unique tags that are globally displayed, with options to customize their position and icon. It offers seamless integration across multiple platforms and supports various programming languages.</p>"},{"location":"#features","title":"Features","text":"<ul> <li>Customizable Tags: Players can personalize their tags, choosing their text, position, and icon.</li> <li>Multilingual Support: Use GlobalTags in various programming languages, including Java, JavaScript and TypeScript.</li> <li>Custom Authentication: Extend the API with custom auth providers for a wider range of supported platforms.</li> </ul> <p>Feel free to explore the documentation and start building with GlobalTags!</p>"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#general","title":"General","text":""},{"location":"faq/#what-do-the-different-role-icons-mean","title":"What do the different role icons mean?","text":"Icon Role <p>Admin</p> <p>Developer</p> <p>Discord Moderator</p> <p>Partner</p> <p>Financial Supporter / Discord Booster</p>"},{"location":"faq/#which-commands-can-i-use","title":"Which commands can I use?","text":"<p>There are several commands to help manage your settings. The main command is <code>/globaltags</code>, or you can use the shorthand <code>/gt</code>. Here are the available subcommands:</p> <ul> <li><code>/gt</code> (1) - Displays the current API and Agent versions.<ul> <li><code>/gt clearcache</code> (2) \u2013 Instantly clears your cache.</li> <li><code>/gt renewcache</code> (3) \u2013 Manually renews the cache.</li> <li><code>/gt link</code> (4) \u2013 Links your Minecraft account to external connections.<ul> <li><code>discord</code> - Begins the process to link your Minecraft account with your Discord. Join our Discord Server to complete the connection.</li> <li><code>email &lt;email&gt;</code> - Adds an email to receive account-related updates. This is not a newsletter.</li> </ul> </li> <li><code>/gt unlink</code> (5) \u2013 Removes external connections from your Minecraft account.<ul> <li><code>discord</code> - Unlinks your Minecraft account from Discord.</li> <li><code>email &lt;email&gt;</code> - Removes your email from the account.</li> </ul> </li> <li><code>/gt verify</code> (6) - Verifies specific connections.<ul> <li><code>email &lt;code&gt;</code> - Verifies your email by entering the confirmation code sent to your inbox.</li> </ul> </li> </ul> </li> </ul> <ol> <li> <p>Base Command:</p> <ul> <li>Alias: <code>/globaltags</code></li> </ul> </li> <li> <p>Clear Cache: </p> <ul> <li>Alias: <code>/gt cc</code></li> </ul> </li> <li> <p>Renew Cache:</p> <ul> <li>Aliases: <code>/gt renew</code>, <code>/gt rc</code></li> </ul> </li> <li> <p>Link Connection: </p> <ul> <li>No aliases</li> </ul> </li> <li> <p>Unlink Connection: </p> <ul> <li>No aliases</li> </ul> </li> <li> <p>Verify Connection: </p> <ul> <li>No aliases</li> </ul> </li> </ol>"},{"location":"faq/#tags","title":"Tags","text":""},{"location":"faq/#how-can-i-use-colors-in-my-tag","title":"How can I use colors in my Tag?","text":"<p>You can customize your tag with colors using Minecraft's default color codes. To add a color to your tag, simply include the appropriate color code before your text. The codes range from <code>0-9</code> for various numbers, and <code>a-f</code> for letters, along with additional codes for effects like bold or italic text. </p> All Minecraft color codes <p>Here's a quick reference for Minecraft's color codes:</p> <ul> <li><code>0</code> - Black</li> <li><code>1</code> - Dark Blue</li> <li><code>2</code> - Dark Green</li> <li><code>3</code> - Dark Aqua</li> <li><code>4</code> - Dark Red</li> <li><code>5</code> - Dark Purple</li> <li><code>6</code> - Gold</li> <li><code>7</code> - Gray</li> <li><code>8</code> - Dark Gray</li> <li><code>9</code> - Blue</li> <li><code>a</code> - Green</li> <li><code>b</code> - Aqua</li> <li><code>c</code> - Red</li> <li><code>d</code> - Light Purple</li> <li><code>e</code> - Yellow</li> <li><code>f</code> - White</li> <li><code>k</code> - Obfuscated</li> <li><code>l</code> - Bold</li> <li><code>m</code> - Strikethrough</li> <li><code>n</code> - Underlined</li> <li><code>o</code> - Italic</li> </ul> <p>Hex colors are not supported yet, but this feature may be added in the future. To apply these codes, use the <code>&amp;</code> symbol followed by the code, like this:</p>  Tag Result <pre><code>&amp;aThis is a green tag\n</code></pre> <p></p> <p>Note</p> <p>Please do NOT put spaces after color codes as this will create a whitespace which is a rule violation.</p> <p>Do - <code>&amp;eExample</code> Don't - <code>&amp;e Example</code></p>"},{"location":"faq/#why-cant-i-include-certain-words-in-my-tag","title":"Why can't I include certain words in my Tag?","text":"<p>Certain words, such as \"LabyMod\", are on a blocklist to prevent users from impersonating staff members. For example, setting your tag to something like <code>&amp;f&amp;lLabyMod &amp;cModerator</code> could closely mimic official staff tags. This blocklist helps maintain authenticity and prevents confusion among users.</p>"},{"location":"rules/","title":"GlobalTags Rules","text":"<p>The GlobalTags system is provided for use by players and developers in the Minecraft community. We allow a lot of freedom in the choice of tags, but there are some limits that must not be exceeded. Your use of the service is subject to the following conditions:</p> <ol> <li>Advertisement of any kind is allowed.</li> <li>Any form of racism/extremism is not allowed.</li> <li>Curse words are allowed as long as they don't insult or target a specific user or group</li> <li>Sharing any information about another person without their consent is strictly forbidden. This is also referred to as doxing.</li> <li>Icons must not include inappropriate content, such as NSFW material, gore, or other offensive imagery.</li> <li>You must not violate any applicable laws or regulations.</li> <li>It is not allowed to exploit bugs or vulnerabilities within the API or mod implementation to gain unfair advantage.</li> </ol> <p>Violating these rules may result in a permanent suspension from GlobalTags services, without any refunds for prior purchases. See General Terms and Conditions</p>"},{"location":"api/custom-auth-provider/","title":"Creating your own auth provider for the API","text":"<p>Thank you for your interest in contributing to the GlobalTags API! Contributions are welcome and greatly appreciated.</p>"},{"location":"api/custom-auth-provider/#setting-up-your-development-environment","title":"Setting Up Your Development Environment","text":"<ol> <li>Create a fork of the API repository</li> <li>Clone your fork of the Repository</li> <li> <p>Install Dependencies</p> <p>Ensure you have bun installed. Then run: <pre><code>bun i\n</code></pre></p> </li> <li> <p>Create a config</p> <p>See Create a Configuration File</p> </li> <li> <p>Run the API <pre><code>bun dev\n</code></pre></p> </li> </ol>"},{"location":"api/custom-auth-provider/#step-by-step-guide","title":"Step-by-Step Guide","text":"Info <p>The GlobalTags API uses an <code>AuthProvider</code> class to handle authentication. To extend the authentication mechanism, you can implement your own class by extending <code>src/auth/AuthProvider</code>.</p> Basic Information <p>As outlined in the How Authentication Works section, the <code>Authorization</code> header must consist of two values: <code>id</code> and <code>token</code>.</p> <p>You need to define the following values:</p> <ul> <li><code>id</code>: The unique identifier for your provider. In this example, we'll use <code>Testing</code> as the <code>id</code>.</li> <li> <p><code>name</code>: A descriptive name for your service, such as the name of the authentication mechanism. In this example, we'll use <code>MyService</code> as the <code>name</code>. (1)</p> <ol> <li>This <code>name</code> is used only for naming files and classes; it has no effect on the code itself.</li> </ol> </li> </ul> <p>If you're unsure about the implementation, you can refer to the existing <code>AuthProvider</code> implementations for guidance.</p>"},{"location":"api/custom-auth-provider/#1-create-a-new-authprovider-class","title":"1. Create a New <code>AuthProvider</code> Class","text":"<p>Create a new file in the <code>src/auth/providers</code> directory, for example, <code>MyServiceProvider.ts</code>, that extends <code>AuthProvider</code>. You need to implement the <code>#getUUID</code> method and initialize the constructor.</p> <pre><code>import AuthProvider from \"../AuthProvider\";\n\nexport default class MyServiceProvider extends AuthProvider {\n    constructor() {\n        super('Testing'); // (1)\n    }\n\n    async getUUID(token: string): Promise&lt;string | null&gt; { // (2)\n        return \"00000000-0000-0000-0000-000000000000\"; // (3)\n    }\n}\n</code></pre> <ol> <li>This is the <code>id</code> value for your provider.</li> <li>The <code>token</code> parameter refers only to the token itself and does not include the authentication provider <code>id</code>.</li> <li>Implement the logic to securely verify the token. This could involve an API request or verifying a JWT. Return <code>null</code> if the token does not map to a valid UUID.</li> </ol>"},{"location":"api/custom-auth-provider/#2-test-your-custom-authprovider","title":"2. Test Your Custom <code>AuthProvider</code>","text":"<p>To test your custom authentication provider, send a <code>POST</code> request to <code>/players/&lt;uuid&gt;</code> with the appropriate <code>Authorization</code> header in the format <code>&lt;id&gt; &lt;token&gt;</code>. For this example, a header could look like this:</p> <pre><code>Authorization: Testing somerandomtoken\n</code></pre>"},{"location":"api/custom-auth-provider/#submitting-changes","title":"Submitting Changes","text":"<p>You can then submit the changes by opening a pull request with a clear title and description of your changes.</p>"},{"location":"api/custom-auth-provider/#license","title":"License","text":"<p>By contributing to GlobalTags API, you agree that your contributions will be licensed under the MIT License.</p> <p>Thank you for your contributions! Your efforts help improve the GlobalTags API for everyone.</p>"},{"location":"api/guide/","title":"GlobalTags API","text":"<p>The GlobalTags API is the core component that enables communication between mod wrappers and the database. This guide will walk you through the usage of the API and offer solutions to common issues.</p> Selfhosting <p>If you want to host your own instance of the GlobalTagsAPI, see the Self-hosting Guide.</p>"},{"location":"api/guide/#available-routes-and-how-to-use-them","title":"Available Routes and How to Use Them","text":"<p>For a complete list of available routes and detailed documentation on how to use them, visit our API documentation. If you're interested in using the API within a specific programming language, don't forget to check out our various language wrappers for implementation examples.</p>"},{"location":"api/guide/#authentication","title":"Authentication","text":"<p>To interact with the GlobalTags API, proper authentication is essential. Here's how our authentication process works:</p>"},{"location":"api/guide/#how-authentication-works","title":"How Authentication Works","text":"<p>You authenticate by passing an <code>Authorization</code> header with your request. This header consists of two parts: the authentication provider ID (<code>id</code>) and the token (<code>token</code>). The format of the header looks like this:</p> <pre><code>Authorization: &lt;id&gt; &lt;token&gt;\n</code></pre>"},{"location":"api/guide/#what-is-an-authentication-provider","title":"What is an Authentication Provider?","text":"<p>An authentication provider (or auth provider for short) is the system that verifies the token and extracts a player's UUID from it. This design allows the API to work flexibly across different environments, ensuring broad compatibility.</p> <p>By using auth providers, we make it easy to integrate GlobalTags with various authentication systems while keeping the API secure and adaptable.</p>"},{"location":"api/guide/#example","title":"Example","text":"Default Authentication Providers <p>Here are the three default authentication providers supported by GlobalTags:</p> <ul> <li>Minecraft (<code>YggdrasilProvider</code>): Requires a Minecraft access token as the <code>token</code> parameter.</li> <li>LabyConnect (<code>LabyConnectProvider</code>): Requires a LabyConnect session token as the <code>token</code> parameter.</li> <li>Bearer (<code>ApiKeyProvider</code>): Requires an API token, which must be manually assigned to an account by staff.</li> </ul> <p>Let's walk through an example to illustrate how the authentication process works. Suppose you send the following <code>Authorization</code> header in your request:</p> <pre><code>Authorization: Minecraft someminecraftsessiontoken\n</code></pre> <p>Here's what happens next:</p> <ol> <li>The API looks for an authentication provider that matches the <code>id</code> - in this case, <code>Minecraft</code>.</li> <li>It verifies the provided token (<code>someminecraftsessiontoken</code>) and attempts to extract a UUID from it.</li> <li>If no matching auth provider is found, or if verification fails, you will receive an error.</li> </ol>"},{"location":"api/guide/#creating-your-own-auth-provider","title":"Creating Your Own Auth Provider","text":"<p>Want to create your own custom authentication provider? This guide covers everything you need to know.</p>"},{"location":"api/guide/#image-serving","title":"Image Serving","text":"<p>Icons and role images play a key role in GlobalTags, so the API provides specific routes to serve these images. Below are the routes you can use to access the three types of icons.</p>"},{"location":"api/guide/#accessing-default-global-icons","title":"Accessing Default Global Icons","text":"<p>To load default icons, use the following URL format, replacing <code>&lt;name&gt;</code> with the lowercase name of the icon: <pre><code>https://cdn.rappytv.com/globaltags/icons/&lt;name&gt;.png\n</code></pre></p>"},{"location":"api/guide/#accessing-custom-global-icons","title":"Accessing Custom Global Icons","text":"<p>For custom per-player icons, you\u2019ll need the <code>hash</code> value, which can be obtained by making a <code>GET</code> request to <code>/players/&lt;uuid&gt;</code> and retrieving the <code>icon.hash</code> key. Then, use the following URL format: <pre><code>https://api.globaltags.xyz/players/&lt;uuid&gt;/icon/&lt;hash&gt;\n</code></pre></p>"},{"location":"api/guide/#accessing-role-icons","title":"Accessing Role Icons","text":"<p>To load role-specific icons, use the URL format below, replacing <code>&lt;name&gt;</code> with the role name: <pre><code>https://cdn.rappytv.com/globaltags/icons/role/&lt;name&gt;.png\n</code></pre></p>"},{"location":"api/guide/#troubleshooting","title":"Troubleshooting","text":""},{"location":"api/guide/#1-malformed-authorization-header","title":"1. Malformed authorization header","text":"<p>Error message: <code>You've entered a malformed authorization header!</code></p> <p>Cause: This error occurs when you either omit the <code>Authorization</code> header for a protected route or provide an invalid auth provider <code>id</code> that doesn't match any registered providers.</p> <p>Solution: Ensure that the <code>Authorization</code> header follows the correct format:</p> <p><pre><code>Authorization: &lt;auth provider id&gt; &lt;token&gt;\n</code></pre> Verify that the auth provider <code>id</code> is valid and corresponds to a registered provider.</p>"},{"location":"api/guide/#2-database-connection-issue","title":"2. Database Connection Issue","text":"<p>Error message: <code>The database is not connected. Please try again later!</code></p> <p>Cause: This error indicates that the API could not establish a connection to the database.</p> <p>Solution: Wait for a few minutes, as this issue is often temporary. If the problem persists for more than 5 minutes, please report it to our team through our Discord Server.</p>"},{"location":"api/guide/#3-unknown-error","title":"3. Unknown Error","text":"<p>Error message: <code>An unknown error ocurred! Please try again later</code></p> <p>Cause: This error occurs due to an internal issue while processing your request. The system returns a generic error message to avoid exposing sensitive information.</p> <p>Solution: Be patient, as resubmitting the request likely won't fix the issue. However, the development team will be automatically notified, and we will work on resolving it. If the error resolves itself, feel free to continue.</p>"},{"location":"api/self-hosting/","title":"Self-hosting the GlobalTagsAPI","text":""},{"location":"api/self-hosting/#prerequisites","title":"Prerequisites","text":"<ul> <li>Bun</li> <li>A MongoDB instance</li> <li>Docker<ul> <li>Docker Compose (Optional)</li> </ul> </li> </ul>"},{"location":"api/self-hosting/#installation","title":"Installation","text":""},{"location":"api/self-hosting/#1-clone-the-repository","title":"1. Clone the Repository","text":"<p>Start by cloning the repository to your local machine:</p> <pre><code>git clone https://github.com/Global-Tags/API gtapi\ncd gtapi\n</code></pre>"},{"location":"api/self-hosting/#2-create-a-configuration-file","title":"2. Create a Configuration File","text":"<p>Next, create a configuration file by copying the example provided. Adjust the settings in <code>config.json</code> as needed. The only mandatory change is the <code>srv</code> field, which should contain the connection string to your MongoDB instance.</p> <pre><code>cp config.json.example config.json\n</code></pre>"},{"location":"api/self-hosting/#3-running-the-api","title":"3. Running the API","text":""},{"location":"api/self-hosting/#run-with-bun-that-rhymes","title":"Run with Bun (that rhymes)","text":"<ol> <li> <p>Install Required Dependencies</p> <p>Use the following command to install the necessary dependencies:</p> <pre><code>bun i\n</code></pre> </li> <li> <p>Start the API</p> <p>To run the API, execute:</p> <pre><code>bun start\n</code></pre> </li> </ol> Hosting the API <p>To keep the API online, install a tool called <code>pm2</code> to daemonize the process: <pre><code># Install pm2 and pm2-logrotate globally\nbun i -g pm2 pm2-logrotate\n\n# Start the daemon\npm2 start src/index.ts --interpreter ~/.bun/bin/bun --name GlobalTagAPI\n</code></pre></p>"},{"location":"api/self-hosting/#run-with-docker","title":"Run with Docker","text":"<p>You have two options for running the API with Docker:</p> <ul> <li> <p>Option 1: Using Docker Compose</p> <p>Run the following command to start the API in detached mode:</p> <pre><code>docker compose up -d # (1)\n</code></pre> <ol> <li>If you'd like to test the setup, you can omit the <code>-d</code> option to run it in the foreground.</li> </ol> </li> <li> <p>Option 2: Without Docker Compose</p> <p>You can also run the API without Docker Compose by executing:</p> <pre><code>docker run -p 5000:5000 $(docker build -q .)\n</code></pre> </li> </ul>"},{"location":"implementations/fabric/","title":"Fabric Mod","text":"<p>In development</p> <p>We're currently working on a Fabric version of GlobalTags. As this is a pretty complicated process we kindly ask you to be patient :)</p> <p>If you have good fabric and mixin knowledge and you want to contribute, feel free to create a ticket on our Discord Server!</p>"},{"location":"implementations/labymod/","title":"LabyMod Addon","text":"Fun Fact <p>Did you know that the original idea behind GlobalTags was to create a simple LabyMod addon just for friends? It was later released to the public and expanded to support a wider range of environments!</p>"},{"location":"implementations/labymod/#installation","title":"Installation","text":"<p>You can easily install the addon by searching for \"GlobalTags\" in the LabyMod Addon Store. It is available for all versions.</p> <p></p>"},{"location":"implementations/labymod/#how-to-set-a-custom-tag","title":"How to Set a Custom Tag","text":"<p>To create a custom tag, follow these steps:</p> <ol> <li>Go to the addon settings.</li> <li>Click the cogwheel icon next to \"Global tag settings.\"</li> </ol> <p></p> <p>In the settings, you'll see a tag preview and an input field. Enter your desired tag (1), select a position for the tag, choose an icon, and click \"Update\" to apply the changes.</p> <ol> <li>You can also use color codes. For more info read How can I use colors in my Tag?.</li> </ol> <p></p>"},{"location":"implementations/labymod/#how-to-appeal-a-ban","title":"How to Appeal a Ban","text":"<p>If you've been banned, it's likely for a significant rule violation, and you'll probably only be granted one second chance. To appeal your ban:</p> <ol> <li>Go to the Global tag settings, where you'll see the ban reason and an \"Appeal\" button.</li> <li>If the appeal button is grayed-out, an admin has disabled appeals for your ban, meaning there may be no option for unbanning.</li> </ol> <p></p> <p>If the appeal button is clickable, a modal will pop up with an input field. Write your apology or the reason you believe the ban should be lifted, and click \"Send appeal.\" Your appeal will be reviewed, and a decision will be made on whether to lift the ban.</p> <p></p>"},{"location":"wrappers/java/","title":"Java Wrapper","text":"Warning <p>You'll need Java Development Kit (JDK) 17 or higher to be able to use the wrapper. This may change in the future.</p>"},{"location":"wrappers/java/#overview","title":"Overview","text":"<p>The GlobalTags Java Wrapper provides an easy-to-use class for interacting with the GlobalTags API. This wrapper simplifies the integration of custom player tags in a Minecraft mod, enabling developers to fetch tag data including the player's tag, icon, and roles. It offers various methods to authenticate with the API, handle cache, and translate color codes for text display.</p>"},{"location":"wrappers/java/#features","title":"Features","text":"<ul> <li>API interaction through a well-defined abstact class.</li> <li>Customizable color code translation for Minecraft text.</li> <li>Authentication support for different methods (e.g., token-based auth).</li> <li>Cache management to optimize performance.</li> <li>User agent customization for API identification.</li> <li>Multilingual support for API responses.</li> </ul>"},{"location":"wrappers/java/#dependency-installation","title":"Dependency installation","text":"<p>To use this wrapper in your Java project, you can add it via Maven or Gradle. The package includes all necessary dependencies and models required to integrate the GlobalTags API into your mod. You don't need to add a seperate repository as it's hosted on Maven Central.</p> Warning <p>You need to replace <code>VERSION</code> with the version you want to use. This is the latest stable tag: </p>  Maven Gradle (Kotlin DSL) Gradle (Groovy) <pre><code>&lt;dependencies&gt;\n  &lt;dependency&gt;\n    &lt;groupId&gt;com.rappytv.globaltags&lt;/groupId&gt;\n    &lt;artifactId&gt;GlobalTagsJava&lt;/artifactId&gt;\n    &lt;version&gt;VERSION&lt;/version&gt;\n  &lt;/dependency&gt;\n&lt;/dependencies&gt;\n</code></pre> <pre><code>dependencies {\n    compileOnly(\"com.rappytv.globaltags:GlobalTagsJava:VERSION\")\n}\n</code></pre> <pre><code>dependencies {\n    compileOnly \"com.rappytv.globaltags:GlobalTagsJava:VERSION\"\n}\n</code></pre>"},{"location":"wrappers/java/#usage","title":"Usage","text":"<p>To implement the wrapper, create a class that extends the <code>GlobalTagsAPI&lt;T&gt;</code> class. This will give you access to a wide range of methods to interact with the GlobalTags API, such as fetching player information, translating color codes, handling authentication, and more.</p>"},{"location":"wrappers/java/#example-implementation","title":"Example Implementation","text":"MyGlobalTagsAPI.java Main.java <pre><code>public class MyGlobalTagsAPI implements GlobalTagsAPI&lt;String&gt; { // (1)\n\n    @Override\n    public Agent getAgent() {\n        return new Agent(\"MyMod\", \"v1.0.0\", \"1.21\"); // (2)\n    }\n\n    @Override\n    public String getLanguageCode() {\n        return \"en_us\"; // (3)\n    }\n\n    @Override\n    public String translateColorCodes(String input) {\n        return input; // (4)\n    }\n\n    @Override\n    public UUID getClientUUID() {\n        return UUID.randomUUID(); // (5)\n    }\n\n    @Override\n    public AuthProvider getAuthType() {\n        return AuthProvider.YGGDRASIL; // (6)\n    }\n\n    @Override\n    public String getAuthorization() {\n        return \"my-api-token\"; // (7)\n    }\n}\n</code></pre> <ol> <li>The <code>T</code> generic in <code>GlobalTagsAPI&lt;T&gt;</code> represents the type used for colored text components. It allows flexibility in how you implement color formatting, whether as a simple <code>String</code>, a <code>TextComponent</code>, or another type. Please note that the <code>ApiHandler&lt;T&gt;</code> and the <code>PlayerInfo&lt;T&gt;</code> also need to use the same generic value as the <code>GlobalTagsAPI&lt;T&gt;</code>.</li> <li> <ol> <li>Argument - Wrapper name</li> <li>Argument - Wrapper version</li> <li>Argument - Minecraft version</li> </ol> </li> <li>Send a language code to the api. If we have translations for this language, any api response will be localized. This method does not need to be overridden. Just remove it if you don't plan to implement localized responses.</li> <li>Here you can implement your logic to convert a string to a colored instance of your <code>T</code> class. For simplicity, this example returns the input as is.</li> <li>Return the current client's UUID. For simplicity, this example returns a random <code>UUID</code>.</li> <li>Here you can choose an authentication method. For this example we'll assume you use minecraft session token based authentication.</li> <li>Here you can return the current auth token of the client.</li> </ol> <pre><code>public class Main {\n\n    private static GlobalTagsAPI&lt;String&gt; api;\n\n    public static void main(String[] args) {\n        // Create an instance of your implementation and save it in some kind of field or attribute\n        api = new MyGlobalTagsAPI();\n\n        // Fetch a player's tag data, cache it and print it out once resolved\n        api.getCache().resolve(uuid, System.out::println);\n\n        // Fetch the client's tag data, cache it and print it out once resolved (The client's uuid is the uuid specified in GlobalTagsAPI#getClientUUID)\n        api.getCache().resolveSelf(System.out::println);\n\n        // Fetch a player's tag data without caching it and print it out once resolved\n        api.getApiHandler().getInfo(uuid, System.out::println);\n\n        // Get a player's tag from the cache (or null if it's not in the cache)\n        System.out.println(api.getCache().get(uuid).getTag());\n\n        // Report a player and log the response message\n        api.getApiHandler().reportPlayer(uuid, \"Racism\", (response) -&gt; System.out.println(response.data()));\n\n        // Get a player's ban reason (Note: This will only work on accounts with the GlobalTags admin permissions)\n        PlayerInfo&lt;String&gt; info = api.getCache().get(uuid);\n        System.out.println(info.isSuspended() ? info.getSuspension().getReason() : \"The user is not banned.\"); // (1)\n\n        // Clear the cache\n        api.getCache().clear();\n\n        // Renew the cache (2)\n        api.getCache().renew();\n    }\n}\n</code></pre> <ol> <li><code>Suspension#getReason</code> will not be null as long as <code>Suspension#isActive</code> is true</li> <li>Renewing the cache means refetching the tag data for every cached player without removing them from the cache.</li> </ol> <p>Also, everything is documented with javadocs so everything should be pretty self-explanatory. If you have any questions don't hesitate to create a new issue or create a ticket on the Discord Server.</p>"},{"location":"wrappers/java/#caching","title":"Caching","text":"<p>The wrapper comes with a built-in caching mechanism to minimize redundant API calls. By default, cached data is refreshed every 5 minutes and completely cleared every 30 minutes.</p> Custom cache intervals <p>You can customize the cache renewal and clearing intervals by creating your own <code>PlayerInfo.Cache&lt;T&gt;</code> instance using the constructor with the <code>options</code> parameter. After that, simply override the <code>GlobalTagsAPI#getCache</code> method to return your custom cache instance.</p> <p>Using the example from above it would look like this:</p> <pre><code>public class MyGlobalTagsAPI implements GlobalTagsAPI&lt;String&gt; {\n\n    private final PlayerInfo.Cache&lt;T&gt; cache = new PlayerInfo.Cache&lt;&gt;(this, new PlayerInfo.Cache.Options() {\n        @Override\n        public long getCacheClearInterval() {\n            // 10 minutes for example\n            return 1000 * 60 * 10;\n        }\n\n        @Override\n        public long getCacheRenewInterval() {\n            // 2 minutes for example\n            return 1000 * 60 * 2;\n        }\n    });\n\n    @Override\n    public Agent getAgent() {\n        return new Agent(\"MyMod\", \"v1.0.0\", \"1.21\");\n    }\n\n    @Override\n    public String getLanguageCode() {\n        return \"en_us\";\n    }\n\n    @Override\n    public String translateColorCodes(String input) {\n        return input;\n    }\n\n    @Override\n    public UUID getClientUUID() {\n        return UUID.randomUUID();\n    }\n\n    // Override the cache getter here\n    @Override\n    public PlayerInfo.Cache&lt;T&gt; getCache() {\n        return cache;\n    }\n\n    @Override\n    public AuthProvider getAuthType() {\n        return AuthProvider.YGGDRASIL;\n    }\n\n    @Override\n    public String getAuthorization() {\n        return \"my-api-token\";\n    }\n}\n</code></pre>"},{"location":"wrappers/java/#authentication","title":"Authentication","text":"<p>To authenticate with the API, you need to provide an authorization token or other credentials depending on the authentication method (<code>AuthProvider</code>). To create an own auth mechanism for the API please read this page.</p>"},{"location":"wrappers/java/#examples","title":"Examples","text":"<p>You can see production examples here:</p> <ul> <li>LabyMod Addon: [GitHub]</li> </ul>"},{"location":"wrappers/typescript/","title":"Typescript Wrapper","text":"Danger <p>This is subject to change. The Typescript wrapper will receive an update with a lot of breaking changes soon.</p>"},{"location":"wrappers/typescript/#dependency-installation","title":"Dependency installation","text":"<p>To use this wrapper in your JavaScript/TypeScript app, you can add it via the npm registry.</p>  npm bun pnpm yarn <pre><code>npm i globaltags.ts\n</code></pre> <pre><code>bun i globaltags.ts\n</code></pre> <pre><code>pnpm add globaltags.ts\n</code></pre> <pre><code>yarn add globaltags.ts\n</code></pre>"},{"location":"wrappers/typescript/#imports","title":"Imports","text":"<p>After adding the dependency you can import the actual API class like this:</p>  ES7 CommonJS <pre><code>import { GlobalTagAPI } from \"globaltags.ts\";\n</code></pre> <pre><code>const { GlobalTagAPI } = require('globaltags.ts');\n</code></pre>"},{"location":"wrappers/typescript/#usage","title":"Usage","text":"<p>To use the wrapper you only need to instantiate a new <code>GlobalTagAPI</code> object. You can then use <code>GlobalTagAPI#fetchPlayer</code> to fetch player data and receive an instance of the <code>Player</code> class.</p> <pre><code>const api = new GlobalTagAPI(); // (1)\n\n// Get a player instance from a specific player uuid\nconst player = await api.fetchPlayer('&lt;UUID&gt;', { token: '&lt;YOUR API KEY&gt;' }).catch(() =&gt; null);\n\nif(!player) return;\n\n// You can now interact with the player data.\nconsole.log(player.tag || 'No Tag'); // (2)\n\nplayer.setTag('The new tag :o', { token: 'current auth token' }); // (3)\n\nplayer.appealBan('I want to apologize', { token: 'token' }); // (4)\n</code></pre> <ol> <li>If you want to use a custom instance of the api you need to pass an options object</li> <li>Log the player's current tag if it exists.</li> <li>Update the player's tag IF you have the admin permission to do so.</li> <li>Appeal your ban if you were banned by an administrator.</li> </ol>"},{"location":"wrappers/typescript/#contributing","title":"Contributing","text":"<p>If you find any bugs or have feature ideas feel free to create an issue.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to GlobalTags","text":"We're looking for developers! <p>We're currently working on a Fabric version of GlobalTags. If you have good fabric and mixin knowledge and you want to contribute, feel free to create a ticket on our Discord Server!</p> <p>GlobalTags is an API designed to enhance player experiences by allowing users to create custom tags visible to everyone using the addon. This documentation will guide you through integrating, customizing, and extending GlobalTags for your project.</p>"},{"location":"#what-is-globaltags","title":"What is GlobalTags?","text":"<p>GlobalTags enables players to create unique tags that are globally displayed, with options to customize their position and icon. It offers seamless integration across multiple platforms and supports various programming languages.</p>"},{"location":"#features","title":"Features","text":"<ul> <li>Customizable Tags: Players can personalize their tags, choosing their text, position, and icon.</li> <li>Multilingual Support: Use GlobalTags in various programming languages, including Java, JavaScript and TypeScript.</li> <li>Custom Authentication: Extend the API with custom auth providers for a wider range of supported platforms.</li> </ul> <p>Feel free to explore the documentation and start building with GlobalTags!</p>"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#general","title":"General","text":""},{"location":"faq/#what-do-the-different-role-icons-mean","title":"What do the different role icons mean?","text":"Icon Role <p>Admin</p> <p>Developer</p> <p>Discord Moderator</p> <p>Partner</p> <p>Financial Supporter / Discord Booster</p>"},{"location":"faq/#which-commands-can-i-use","title":"Which commands can I use?","text":"<p>There are several commands to help manage your settings. The main command is <code>/globaltags</code>, or you can use the shorthand <code>/gt</code>. Here are the available subcommands:</p> <ul> <li><code>/gt</code> (1) - Displays the current API and Agent versions.<ul> <li><code>/gt clearcache</code> (2) \u2013 Instantly clears your cache.</li> <li><code>/gt renewcache</code> (3) \u2013 Manually renews the cache.</li> <li><code>/gt link</code> (4) \u2013 Links your Minecraft account to external connections.<ul> <li><code>discord</code> - Begins the process to link your Minecraft account with your Discord. Join our Discord Server to complete the connection.</li> <li><code>email &lt;address&gt;</code> - Adds an email to receive account-related updates. This is not a newsletter.</li> </ul> </li> <li><code>/gt unlink</code> (5) \u2013 Removes external connections from your Minecraft account.<ul> <li><code>discord</code> - Unlinks your Minecraft account from Discord.</li> <li><code>email</code> - Removes your email from the account.</li> </ul> </li> <li><code>/gt verify</code> (6) - Verifies specific connections.<ul> <li><code>email &lt;code&gt;</code> - Verifies your email by entering the confirmation code sent to your inbox.</li> </ul> </li> </ul> </li> </ul> <ol> <li> <p>Base Command:</p> <ul> <li>Alias: <code>/globaltags</code></li> </ul> </li> <li> <p>Clear Cache: </p> <ul> <li>Alias: <code>/gt cc</code></li> </ul> </li> <li> <p>Renew Cache:</p> <ul> <li>Aliases: <code>/gt renew</code>, <code>/gt rc</code></li> </ul> </li> <li> <p>Link Connection: </p> <ul> <li>No aliases</li> </ul> </li> <li> <p>Unlink Connection: </p> <ul> <li>No aliases</li> </ul> </li> <li> <p>Verify Connection: </p> <ul> <li>No aliases</li> </ul> </li> </ol>"},{"location":"faq/#tags","title":"Tags","text":""},{"location":"faq/#how-can-i-use-colors-in-my-tag","title":"How can I use colors in my Tag?","text":"<p>You can customize your tag with colors using Minecraft's default color codes. To add a color to your tag, simply include the appropriate color code before your text. The codes range from <code>0-9</code> for various numbers, and <code>a-f</code> for letters, along with additional codes for effects like bold or italic text. </p> All Minecraft color codes <p>Here's a quick reference for Minecraft's color codes:</p> <ul> <li><code>0</code> - Black</li> <li><code>1</code> - Dark Blue</li> <li><code>2</code> - Dark Green</li> <li><code>3</code> - Dark Aqua</li> <li><code>4</code> - Dark Red</li> <li><code>5</code> - Dark Purple</li> <li><code>6</code> - Gold</li> <li><code>7</code> - Gray</li> <li><code>8</code> - Dark Gray</li> <li><code>9</code> - Blue</li> <li><code>a</code> - Green</li> <li><code>b</code> - Aqua</li> <li><code>c</code> - Red</li> <li><code>d</code> - Light Purple</li> <li><code>e</code> - Yellow</li> <li><code>f</code> - White</li> <li><code>k</code> - Obfuscated</li> <li><code>l</code> - Bold</li> <li><code>m</code> - Strikethrough</li> <li><code>n</code> - Underlined</li> <li><code>o</code> - Italic</li> </ul> <p>Hex colors are not supported yet, but this feature may be added in the future. To apply these codes, use the <code>&amp;</code> symbol followed by the code, like this:</p>  Tag Result <pre><code>&amp;aThis is a green tag\n</code></pre> <p></p> <p>Note</p> <p>Please do NOT put spaces after color codes as this will create a whitespace which is a rule violation.</p> <p>Do - <code>&amp;eExample</code> Don't - <code>&amp;e Example</code></p>"},{"location":"faq/#why-cant-i-include-certain-words-in-my-tag","title":"Why can't I include certain words in my Tag?","text":"<p>Certain words, such as \"LabyMod\", are on a blocklist to prevent users from impersonating staff members. For example, setting your tag to something like <code>&amp;f&amp;lLabyMod &amp;cModerator</code> could closely mimic official staff tags. This blocklist helps maintain authenticity and prevents confusion among users.</p>"},{"location":"rules/","title":"GlobalTags Rules","text":"<p>The GlobalTags system is provided for use by players and developers in the Minecraft community. We allow a lot of freedom in the choice of tags, but there are some limits that must not be exceeded. Your use of the service is subject to the following conditions:</p> <ol> <li>Advertisement of any kind is allowed.</li> <li>Any form of racism/extremism is not allowed.</li> <li>Curse words are allowed as long as they don't insult or target a specific user or group</li> <li>Sharing any information about another person without their consent is strictly forbidden. This is also referred to as doxing.</li> <li>Icons must not include inappropriate content, such as NSFW material, gore, or other offensive imagery.</li> <li>You must not violate any applicable laws or regulations.</li> <li>It is not allowed to exploit bugs or vulnerabilities within the API or mod implementation to gain unfair advantage.</li> </ol> <p>Violating these rules may result in a permanent suspension from GlobalTags services, without any refunds for prior purchases. See General Terms and Conditions</p>"},{"location":"api/custom-auth-provider/","title":"Creating your own auth provider for the API","text":"<p>Thank you for your interest in contributing to the GlobalTags API! Contributions are welcome and greatly appreciated.</p>"},{"location":"api/custom-auth-provider/#setting-up-your-development-environment","title":"Setting Up Your Development Environment","text":"<ol> <li>Create a fork of the API repository</li> <li>Clone your fork of the Repository</li> <li> <p>Install Dependencies</p> <p>Ensure you have bun installed. Then run: <pre><code>bun i\n</code></pre></p> </li> <li> <p>Create a config</p> <p>See Create a Configuration File</p> </li> <li> <p>Run the API <pre><code>bun dev\n</code></pre></p> </li> </ol>"},{"location":"api/custom-auth-provider/#step-by-step-guide","title":"Step-by-Step Guide","text":"Info <p>The GlobalTags API uses an <code>AuthProvider</code> class to handle authentication. To extend the authentication mechanism, you can implement your own class by extending <code>src/auth/AuthProvider</code>.</p> Basic Information <p>As outlined in the How Authentication Works section, the <code>Authorization</code> header must consist of two values: <code>id</code> and <code>token</code>.</p> <p>You need to define the following values:</p> <ul> <li><code>id</code>: The unique identifier for your provider. In this example, we'll use <code>Testing</code> as the <code>id</code>.</li> <li> <p><code>name</code>: A descriptive name for your service, such as the name of the authentication mechanism. In this example, we'll use <code>MyService</code> as the <code>name</code>. (1)</p> <ol> <li>This <code>name</code> is used only for naming files and classes; it has no effect on the code itself.</li> </ol> </li> </ul> <p>If you're unsure about the implementation, you can refer to the existing <code>AuthProvider</code> implementations for guidance.</p>"},{"location":"api/custom-auth-provider/#1-create-a-new-authprovider-class","title":"1. Create a New <code>AuthProvider</code> Class","text":"<p>Create a new file in the <code>src/auth/providers</code> directory, for example, <code>MyServiceProvider.ts</code>, that extends <code>AuthProvider</code>. You need to implement the <code>#getUUID</code> method and initialize the constructor.</p> <pre><code>import AuthProvider from \"../AuthProvider\";\n\nexport default class MyServiceProvider extends AuthProvider {\n    constructor() {\n        super('Testing'); // (1)\n    }\n\n    async getUUID(token: string): Promise&lt;string | null&gt; { // (2)\n        return \"00000000-0000-0000-0000-000000000000\"; // (3)\n    }\n}\n</code></pre> <ol> <li>This is the <code>id</code> value for your provider.</li> <li>The <code>token</code> parameter refers only to the token itself and does not include the authentication provider <code>id</code>.</li> <li>Implement the logic to securely verify the token. This could involve an API request or verifying a JWT. Return <code>null</code> if the token does not map to a valid UUID.</li> </ol>"},{"location":"api/custom-auth-provider/#2-test-your-custom-authprovider","title":"2. Test Your Custom <code>AuthProvider</code>","text":"<p>To test your custom authentication provider, send a <code>POST</code> request to <code>/players/&lt;uuid&gt;</code> with the appropriate <code>Authorization</code> header in the format <code>&lt;id&gt; &lt;token&gt;</code>. For this example, a header could look like this:</p> <pre><code>Authorization: Testing somerandomtoken\n</code></pre>"},{"location":"api/custom-auth-provider/#submitting-changes","title":"Submitting Changes","text":"<p>You can then submit the changes by opening a pull request with a clear title and description of your changes.</p>"},{"location":"api/custom-auth-provider/#license","title":"License","text":"<p>By contributing to GlobalTags API, you agree that your contributions will be licensed under the MIT License.</p> <p>Thank you for your contributions! Your efforts help improve the GlobalTags API for everyone.</p>"},{"location":"api/guide/","title":"GlobalTags API","text":"<p>The GlobalTags API is the core component that enables communication between mod wrappers and the database. This guide will walk you through the usage of the API and offer solutions to common issues.</p> Selfhosting <p>If you want to host your own instance of the GlobalTagsAPI, see the Self-hosting Guide.</p>"},{"location":"api/guide/#available-routes-and-how-to-use-them","title":"Available Routes and How to Use Them","text":"<p>For a complete list of available routes and detailed documentation on how to use them, visit our API documentation. If you're interested in using the API within a specific programming language, don't forget to check out our various language wrappers for implementation examples.</p>"},{"location":"api/guide/#authentication","title":"Authentication","text":"<p>To interact with the GlobalTags API, proper authentication is essential. Here's how our authentication process works:</p>"},{"location":"api/guide/#how-authentication-works","title":"How Authentication Works","text":"<p>You authenticate by passing an <code>Authorization</code> header with your request. This header consists of two parts: the authentication provider ID (<code>id</code>) and the token (<code>token</code>). The format of the header looks like this:</p> <pre><code>Authorization: &lt;id&gt; &lt;token&gt;\n</code></pre>"},{"location":"api/guide/#what-is-an-authentication-provider","title":"What is an Authentication Provider?","text":"<p>An authentication provider (or auth provider for short) is the system that verifies the token and extracts a player's UUID from it. This design allows the API to work flexibly across different environments, ensuring broad compatibility.</p> <p>By using auth providers, we make it easy to integrate GlobalTags with various authentication systems while keeping the API secure and adaptable.</p>"},{"location":"api/guide/#example","title":"Example","text":"Default Authentication Providers <p>Here are the three default authentication providers supported by GlobalTags:</p> <ul> <li>Minecraft (<code>YggdrasilProvider</code>): Requires a Minecraft access token as the <code>token</code> parameter.</li> <li>LabyConnect (<code>LabyConnectProvider</code>): Requires a LabyConnect session token as the <code>token</code> parameter.</li> <li>Bearer (<code>ApiKeyProvider</code>): Requires an API token, which must be manually assigned to an account by staff.</li> </ul> <p>Let's walk through an example to illustrate how the authentication process works. Suppose you send the following <code>Authorization</code> header in your request:</p> <pre><code>Authorization: Minecraft someminecraftsessiontoken\n</code></pre> <p>Here's what happens next:</p> <ol> <li>The API looks for an authentication provider that matches the <code>id</code> - in this case, <code>Minecraft</code>.</li> <li>It verifies the provided token (<code>someminecraftsessiontoken</code>) and attempts to extract a UUID from it.</li> <li>If no matching auth provider is found, or if verification fails, you will receive an error.</li> </ol>"},{"location":"api/guide/#creating-your-own-auth-provider","title":"Creating Your Own Auth Provider","text":"<p>Want to create your own custom authentication provider? This guide covers everything you need to know.</p>"},{"location":"api/guide/#image-serving","title":"Image Serving","text":"<p>Icons and role images play a key role in GlobalTags, so the API provides specific routes to serve these images. Below are the routes you can use to access the three types of icons.</p>"},{"location":"api/guide/#accessing-default-global-icons","title":"Accessing Default Global Icons","text":"<p>To load default icons, use the following URL format, replacing <code>&lt;name&gt;</code> with the lowercase name of the icon: <pre><code>https://cdn.rappytv.com/globaltags/icons/&lt;name&gt;.png\n</code></pre></p>"},{"location":"api/guide/#accessing-custom-global-icons","title":"Accessing Custom Global Icons","text":"<p>For custom per-player icons, you\u2019ll need the <code>hash</code> value, which can be obtained by making a <code>GET</code> request to <code>/players/&lt;uuid&gt;</code> and retrieving the <code>icon.hash</code> key. Then, use the following URL format: <pre><code>https://api.globaltags.xyz/players/&lt;uuid&gt;/icon/&lt;hash&gt;\n</code></pre></p>"},{"location":"api/guide/#accessing-role-icons","title":"Accessing Role Icons","text":"<p>To load role-specific icons, use the URL format below, replacing <code>&lt;name&gt;</code> with the role name: <pre><code>https://cdn.rappytv.com/globaltags/icons/role/&lt;name&gt;.png\n</code></pre></p>"},{"location":"api/guide/#troubleshooting","title":"Troubleshooting","text":""},{"location":"api/guide/#1-malformed-authorization-header","title":"1. Malformed authorization header","text":"<p>Error message: <code>You've entered a malformed authorization header!</code></p> <p>Cause: This error occurs when you either omit the <code>Authorization</code> header for a protected route or provide an invalid auth provider <code>id</code> that doesn't match any registered providers.</p> <p>Solution: Ensure that the <code>Authorization</code> header follows the correct format:</p> <p><pre><code>Authorization: &lt;auth provider id&gt; &lt;token&gt;\n</code></pre> Verify that the auth provider <code>id</code> is valid and corresponds to a registered provider.</p>"},{"location":"api/guide/#2-database-connection-issue","title":"2. Database Connection Issue","text":"<p>Error message: <code>The database is not connected. Please try again later!</code></p> <p>Cause: This error indicates that the API could not establish a connection to the database.</p> <p>Solution: Wait for a few minutes, as this issue is often temporary. If the problem persists for more than 5 minutes, please report it to our team through our Discord Server.</p>"},{"location":"api/guide/#3-unknown-error","title":"3. Unknown Error","text":"<p>Error message: <code>An unknown error ocurred! Please try again later</code></p> <p>Cause: This error occurs due to an internal issue while processing your request. The system returns a generic error message to avoid exposing sensitive information.</p> <p>Solution: Be patient, as resubmitting the request likely won't fix the issue. However, the development team will be automatically notified, and we will work on resolving it. If the error resolves itself, feel free to continue.</p>"},{"location":"api/self-hosting/","title":"Self-hosting the GlobalTagsAPI","text":""},{"location":"api/self-hosting/#prerequisites","title":"Prerequisites","text":"<ul> <li>Bun</li> <li>A MongoDB instance</li> <li>Docker<ul> <li>Docker Compose (Optional)</li> </ul> </li> </ul>"},{"location":"api/self-hosting/#installation","title":"Installation","text":""},{"location":"api/self-hosting/#1-clone-the-repository","title":"1. Clone the Repository","text":"<p>Start by cloning the repository to your local machine:</p> <pre><code>git clone https://github.com/Global-Tags/API gtapi\ncd gtapi\n</code></pre>"},{"location":"api/self-hosting/#2-create-a-configuration-file","title":"2. Create a Configuration File","text":"<p>Next, create a configuration file by copying the example provided. Adjust the settings in <code>config.json</code> as needed. The only mandatory change is the <code>srv</code> field, which should contain the connection string to your MongoDB instance.</p> <pre><code>cp config.json.example config.json\n</code></pre>"},{"location":"api/self-hosting/#3-running-the-api","title":"3. Running the API","text":""},{"location":"api/self-hosting/#run-with-bun-that-rhymes","title":"Run with Bun (that rhymes)","text":"<ol> <li> <p>Install Required Dependencies</p> <p>Use the following command to install the necessary dependencies:</p> <pre><code>bun i\n</code></pre> </li> <li> <p>Start the API</p> <p>To run the API, execute:</p> <pre><code>bun start\n</code></pre> </li> </ol> Hosting the API <p>To keep the API online, install a tool called <code>pm2</code> to daemonize the process: <pre><code># Install pm2 and pm2-logrotate globally\nbun i -g pm2 pm2-logrotate\n\n# Start the daemon\npm2 start src/index.ts --interpreter ~/.bun/bin/bun --name GlobalTagAPI\n</code></pre></p>"},{"location":"api/self-hosting/#run-with-docker","title":"Run with Docker","text":"<p>You have two options for running the API with Docker:</p> <ul> <li> <p>Option 1: Using Docker Compose</p> <p>Run the following command to start the API in detached mode:</p> <pre><code>docker compose up -d # (1)\n</code></pre> <ol> <li>If you'd like to test the setup, you can omit the <code>-d</code> option to run it in the foreground.</li> </ol> </li> <li> <p>Option 2: Without Docker Compose</p> <p>You can also run the API without Docker Compose by executing:</p> <pre><code>docker run -p 5000:5000 $(docker build -q .)\n</code></pre> </li> </ul>"},{"location":"implementations/fabric/","title":"Fabric Mod","text":"<p>In development</p> <p>We're currently working on a Fabric version of GlobalTags. As this is a pretty complicated process we kindly ask you to be patient :)</p> <p>If you have good fabric and mixin knowledge and you want to contribute, feel free to create a ticket on our Discord Server!</p>"},{"location":"implementations/labymod/","title":"LabyMod Addon","text":"Fun Fact <p>Did you know that the original idea behind GlobalTags was to create a simple LabyMod addon just for friends? It was later released to the public and expanded to support a wider range of environments!</p>"},{"location":"implementations/labymod/#installation","title":"Installation","text":"<p>You can easily install the addon by searching for \"GlobalTags\" in the LabyMod Addon Store. It is available for all versions.</p> <p></p>"},{"location":"implementations/labymod/#how-to-set-a-custom-tag","title":"How to Set a Custom Tag","text":"<p>To create a custom tag, follow these steps:</p> <ol> <li>Go to the addon settings.</li> <li>Click the cogwheel icon next to \"Global tag settings.\"</li> </ol> <p></p> <p>In the settings, you'll see a tag preview and an input field. Enter your desired tag (1), select a position for the tag, choose an icon, and click \"Update\" to apply the changes.</p> <ol> <li>You can also use color codes. For more info read How can I use colors in my Tag?.</li> </ol> <p></p>"},{"location":"implementations/labymod/#how-to-appeal-a-ban","title":"How to Appeal a Ban","text":"<p>If you've been banned, it's likely for a significant rule violation, and you'll probably only be granted one second chance. To appeal your ban:</p> <ol> <li>Go to the Global tag settings, where you'll see the ban reason and an \"Appeal\" button.</li> <li>If the appeal button is grayed-out, an admin has disabled appeals for your ban, meaning there may be no option for unbanning.</li> </ol> <p></p> <p>If the appeal button is clickable, a modal will pop up with an input field. Write your apology or the reason you believe the ban should be lifted, and click \"Send appeal.\" Your appeal will be reviewed, and a decision will be made on whether to lift the ban.</p> <p></p>"},{"location":"wrappers/java/","title":"Java Wrapper","text":"Warning <p>You'll need Java Development Kit (JDK) 17 or higher to be able to use the wrapper. This may change in the future.</p>"},{"location":"wrappers/java/#overview","title":"Overview","text":"<p>The GlobalTags Java Wrapper provides an easy-to-use class for interacting with the GlobalTags API. This wrapper simplifies the integration of custom player tags in a Minecraft mod, enabling developers to fetch tag data including the player's tag, icon, and roles. It offers various methods to authenticate with the API, handle cache, and translate color codes for text display.</p>"},{"location":"wrappers/java/#features","title":"Features","text":"<ul> <li>API interaction through a well-defined abstact class.</li> <li>Customizable color code translation for Minecraft text.</li> <li>Authentication support for different methods (e.g., token-based auth).</li> <li>Cache management to optimize performance.</li> <li>User agent customization for API identification.</li> <li>Multilingual support for API responses.</li> </ul>"},{"location":"wrappers/java/#dependency-installation","title":"Dependency installation","text":"<p>To use this wrapper in your Java project, you can add it via Maven or Gradle. The package includes all necessary dependencies and models required to integrate the GlobalTags API into your mod. You don't need to add a seperate repository as it's hosted on Maven Central.</p> Warning <p>You need to replace <code>VERSION</code> with the version you want to use. This is the latest stable tag: </p>  Maven Gradle (Kotlin DSL) Gradle (Groovy) <pre><code>&lt;dependencies&gt;\n  &lt;dependency&gt;\n    &lt;groupId&gt;com.rappytv.globaltags&lt;/groupId&gt;\n    &lt;artifactId&gt;GlobalTagsJava&lt;/artifactId&gt;\n    &lt;version&gt;VERSION&lt;/version&gt;\n  &lt;/dependency&gt;\n&lt;/dependencies&gt;\n</code></pre> <pre><code>dependencies {\n    compileOnly(\"com.rappytv.globaltags:GlobalTagsJava:VERSION\")\n}\n</code></pre> <pre><code>dependencies {\n    compileOnly \"com.rappytv.globaltags:GlobalTagsJava:VERSION\"\n}\n</code></pre>"},{"location":"wrappers/java/#usage","title":"Usage","text":"<p>To implement the wrapper, create a class that extends the <code>GlobalTagsAPI&lt;T&gt;</code> class. This will give you access to a wide range of methods to interact with the GlobalTags API, such as fetching player information, translating color codes, handling authentication, and more.</p>"},{"location":"wrappers/java/#example-implementation","title":"Example Implementation","text":"MyGlobalTagsAPI.java Main.java <pre><code>public class MyGlobalTagsAPI implements GlobalTagsAPI&lt;String&gt; { // (1)\n\n    @Override\n    public Agent getAgent() {\n        return new Agent(\"MyMod\", \"v1.0.0\", \"1.21\"); // (2)\n    }\n\n    @Override\n    public String getLanguageCode() {\n        return \"en_us\"; // (3)\n    }\n\n    @Override\n    public String translateColorCodes(String input) {\n        return input; // (4)\n    }\n\n    @Override\n    public UUID getClientUUID() {\n        return UUID.randomUUID(); // (5)\n    }\n\n    @Override\n    public AuthProvider getAuthType() {\n        return AuthProvider.YGGDRASIL; // (6)\n    }\n\n    @Override\n    public String getAuthorization() {\n        return \"my-api-token\"; // (7)\n    }\n}\n</code></pre> <ol> <li>The <code>T</code> generic in <code>GlobalTagsAPI&lt;T&gt;</code> represents the type used for colored text components. It allows flexibility in how you implement color formatting, whether as a simple <code>String</code>, a <code>TextComponent</code>, or another type. Please note that the <code>ApiHandler&lt;T&gt;</code> and the <code>PlayerInfo&lt;T&gt;</code> also need to use the same generic value as the <code>GlobalTagsAPI&lt;T&gt;</code>.</li> <li> <ol> <li>Argument - Wrapper name</li> <li>Argument - Wrapper version</li> <li>Argument - Minecraft version</li> </ol> </li> <li>Send a language code to the api. If we have translations for this language, any api response will be localized. This method does not need to be overridden. Just remove it if you don't plan to implement localized responses.</li> <li>Here you can implement your logic to convert a string to a colored instance of your <code>T</code> class. For simplicity, this example returns the input as is.</li> <li>Return the current client's UUID. For simplicity, this example returns a random <code>UUID</code>.</li> <li>Here you can choose an authentication method. For this example we'll assume you use minecraft session token based authentication.</li> <li>Here you can return the current auth token of the client.</li> </ol> <pre><code>public class Main {\n\n    private static GlobalTagsAPI&lt;String&gt; api;\n\n    public static void main(String[] args) {\n        // Create an instance of your implementation and save it in some kind of field or attribute\n        api = new MyGlobalTagsAPI();\n\n        // Fetch a player's tag data, cache it and print it out once resolved\n        api.getCache().resolve(uuid, System.out::println);\n\n        // Fetch the client's tag data, cache it and print it out once resolved (The client's uuid is the uuid specified in GlobalTagsAPI#getClientUUID)\n        api.getCache().resolveSelf(System.out::println);\n\n        // Fetch a player's tag data without caching it and print it out once resolved\n        api.getApiHandler().getInfo(uuid, System.out::println);\n\n        // Get a player's tag from the cache (or null if it's not in the cache)\n        System.out.println(api.getCache().get(uuid).getTag());\n\n        // Report a player and log the response message\n        api.getApiHandler().reportPlayer(uuid, \"Racism\", (response) -&gt; System.out.println(response.data()));\n\n        // Get a player's ban reason (Note: This will only work on accounts with the GlobalTags admin permissions)\n        PlayerInfo&lt;String&gt; info = api.getCache().get(uuid);\n        System.out.println(info.isSuspended() ? info.getSuspension().getReason() : \"The user is not banned.\"); // (1)\n\n        // Clear the cache\n        api.getCache().clear();\n\n        // Renew the cache (2)\n        api.getCache().renew();\n    }\n}\n</code></pre> <ol> <li><code>Suspension#getReason</code> will not be null as long as <code>Suspension#isActive</code> is true</li> <li>Renewing the cache means refetching the tag data for every cached player without removing them from the cache.</li> </ol> <p>Also, everything is documented with javadocs so everything should be pretty self-explanatory. If you have any questions don't hesitate to create a new issue or create a ticket on the Discord Server.</p>"},{"location":"wrappers/java/#caching","title":"Caching","text":"<p>The wrapper comes with a built-in caching mechanism to minimize redundant API calls. By default, cached data is refreshed every 5 minutes and completely cleared every 30 minutes.</p> Custom cache intervals <p>You can customize the cache renewal and clearing intervals by creating your own <code>PlayerInfo.Cache&lt;T&gt;</code> instance using the constructor with the <code>options</code> parameter. After that, simply override the <code>GlobalTagsAPI#getCache</code> method to return your custom cache instance.</p> <p>Using the example from above it would look like this:</p> <pre><code>public class MyGlobalTagsAPI implements GlobalTagsAPI&lt;String&gt; {\n\n    private final PlayerInfo.Cache&lt;T&gt; cache = new PlayerInfo.Cache&lt;&gt;(this, new PlayerInfo.Cache.Options() {\n        @Override\n        public long getCacheClearInterval() {\n            // 10 minutes for example\n            return 1000 * 60 * 10;\n        }\n\n        @Override\n        public long getCacheRenewInterval() {\n            // 2 minutes for example\n            return 1000 * 60 * 2;\n        }\n    });\n\n    @Override\n    public Agent getAgent() {\n        return new Agent(\"MyMod\", \"v1.0.0\", \"1.21\");\n    }\n\n    @Override\n    public String getLanguageCode() {\n        return \"en_us\";\n    }\n\n    @Override\n    public String translateColorCodes(String input) {\n        return input;\n    }\n\n    @Override\n    public UUID getClientUUID() {\n        return UUID.randomUUID();\n    }\n\n    // Override the cache getter here\n    @Override\n    public PlayerInfo.Cache&lt;T&gt; getCache() {\n        return cache;\n    }\n\n    @Override\n    public AuthProvider getAuthType() {\n        return AuthProvider.YGGDRASIL;\n    }\n\n    @Override\n    public String getAuthorization() {\n        return \"my-api-token\";\n    }\n}\n</code></pre>"},{"location":"wrappers/java/#authentication","title":"Authentication","text":"<p>To authenticate with the API, you need to provide an authorization token or other credentials depending on the authentication method (<code>AuthProvider</code>). To create an own auth mechanism for the API please read this page.</p>"},{"location":"wrappers/java/#examples","title":"Examples","text":"<p>You can see production examples here:</p> <ul> <li>LabyMod Addon: [GitHub]</li> </ul>"},{"location":"wrappers/typescript/","title":"Typescript Wrapper","text":"Danger <p>This is subject to change. The Typescript wrapper will receive an update with a lot of breaking changes soon.</p>"},{"location":"wrappers/typescript/#dependency-installation","title":"Dependency installation","text":"<p>To use this wrapper in your JavaScript/TypeScript app, you can add it via the npm registry.</p>  npm bun pnpm yarn <pre><code>npm i globaltags.ts\n</code></pre> <pre><code>bun i globaltags.ts\n</code></pre> <pre><code>pnpm add globaltags.ts\n</code></pre> <pre><code>yarn add globaltags.ts\n</code></pre>"},{"location":"wrappers/typescript/#imports","title":"Imports","text":"<p>After adding the dependency you can import the actual API class like this:</p>  ES7 CommonJS <pre><code>import { GlobalTagAPI } from \"globaltags.ts\";\n</code></pre> <pre><code>const { GlobalTagAPI } = require('globaltags.ts');\n</code></pre>"},{"location":"wrappers/typescript/#usage","title":"Usage","text":"<p>To use the wrapper you only need to instantiate a new <code>GlobalTagAPI</code> object. You can then use <code>GlobalTagAPI#fetchPlayer</code> to fetch player data and receive an instance of the <code>Player</code> class.</p> <pre><code>const api = new GlobalTagAPI(); // (1)\n\n// Get a player instance from a specific player uuid\nconst player = await api.fetchPlayer('&lt;UUID&gt;', { token: '&lt;YOUR API KEY&gt;' }).catch(() =&gt; null);\n\nif(!player) return;\n\n// You can now interact with the player data.\nconsole.log(player.tag || 'No Tag'); // (2)\n\nplayer.setTag('The new tag :o', { token: 'current auth token' }); // (3)\n\nplayer.appealBan('I want to apologize', { token: 'token' }); // (4)\n</code></pre> <ol> <li>If you want to use a custom instance of the api you need to pass an options object</li> <li>Log the player's current tag if it exists.</li> <li>Update the player's tag IF you have the admin permission to do so.</li> <li>Appeal your ban if you were banned by an administrator.</li> </ol>"},{"location":"wrappers/typescript/#contributing","title":"Contributing","text":"<p>If you find any bugs or have feature ideas feel free to create an issue.</p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index ba48cb4e4b18c70fcb569acb615c280d15ce1950..606733849003756b51c292f707c7cccbc5356172 100644
GIT binary patch
delta 13
Ucmb=gXP58h;9!tanaExN02ZAC4gdfE

delta 13
Ucmb=gXP58h;9xM6naExN02c5A9RL6T