{"_id":"@calico32/hypixel-cache","name":"@calico32/hypixel-cache","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@calico32/hypixel-cache","version":"1.0.0","types":"types.d.ts","dependencies":{"@calico32/hypixel-types":"^0.1.1"},"gitHead":"f15a3bfc24dd05ae58534d5feff2eddd5ec9e98b","description":"A simple cache/intermediary for the [Hypixel API](https://api.hypixel.net/) written in Go. The supplementary npm package contains type definitions for the responses from this cache server.","_id":"@calico32/hypixel-cache@1.0.0","_nodeVersion":"20.1.0","_npmVersion":"9.6.4","dist":{"integrity":"sha512-MZh0RF38YfxE5jw+qPc5QBIgqwSEZJMeQpc8PQAeljTs2CK1GzZ8wZqZNPzmUpslBit6Xypy8h5r7AWD0fGM9Q==","shasum":"cc28efa264cb7f8e15ad5996b847df8b1672f006","tarball":"https://registry.npmjs.org/@calico32/hypixel-cache/-/hypixel-cache-1.0.0.tgz","fileCount":4,"unpackedSize":5088,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIAjKY4TsYAFkS3hsT4vODxaV5gkL+I+bKtCAAqkRTDVJAiEA/QfLTSQzIQa76qrwd+eBsSXdxOiOq9SWseepabsXzzU="}]},"_npmUser":{"name":"calico32","email":"devdoge1+calico32@gmail.com"},"directories":{},"maintainers":[{"name":"calico32","email":"devdoge1+calico32@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/hypixel-cache_1.0.0_1694400427267_0.6149245523504936"},"_hasShrinkwrap":false}},"time":{"created":"2023-09-11T02:47:07.133Z","1.0.0":"2023-09-11T02:47:07.469Z","modified":"2023-09-11T02:47:07.764Z"},"maintainers":[{"name":"calico32","email":"devdoge1+calico32@gmail.com"}],"description":"A simple cache/intermediary for the [Hypixel API](https://api.hypixel.net/) written in Go. The supplementary npm package contains type definitions for the responses from this cache server.","readme":"# hypixel-cache\n\nA simple cache/intermediary for the [Hypixel API](https://api.hypixel.net/) written in Go. The supplementary npm package contains type definitions for the responses from this cache server.\n\n## Configuration\n\nSee [.env.example](./.env.example). Copy to `.env` to use.\n\n## API\n\n`hypixel-cache` supports fetching player data by both UUIDs (which are sent directly to the Hypixel API) and usernames (which are resolved to UUIDs first via a Mojang API).\n\nHypixel player data is kept around for 15-30 minutes. Subsequent requests for the same player will return the cached data.\n\nSimilarly, UUIDs that have been resolved from usernames will be cached for 60-120 minutes. Subsequent requests for the same username will bypass the Mojang API and use the cached UUID. This means if a player changes their username during those 60-120 minutes, both the new and old username will resolve to their UUID.\n\n### Definitions\n\n**API key**: This is a separate, user-defined key for the cache, a.k.a. **NOT** the Hypixel API key. The Hypixel API key is specified in the environment variable `HYPIXEL_API_KEY`.\n\n**Account/Profile**: Minecraft account. If the account exists, then there is someone with the given username/UUID.\n\n**Player**: Hypixel player data. If the player exists, then the account exists and has logged in to Hypixel at least once.\n\n### Requests\n\n```http\nGET /uuid/b41d72aa-0098-45b0-ada5-f154d8796d20\nX-Secret: {api_key}\n```\n\n```http\nGET /uuid/b41d72aa009845b0ada5f154d8796d20\nX-Secret: {api_key}\n```\n\n```http\nGET /name/wiisportsresorts\nX-Secret: {api_key}\n```\n\n### Responses\n\n#### Account exists, player exists\n\n```http\nHTTP/1.1 200 OK\nAccess-Control-Allow-Methods: GET\nAccess-Control-Allow-Origin: *\nAccess-Control-Expose-Headers: X-Response-Time\nX-Response-Time: 123ms\nContent-Type: application/json\n\n{\n  \"success\": true,\n  \"fetchedAt\": \"1970-01-01T00:00:00Z\",\n  \"cached\": false,\n  \"username\": \"…\", // mirrors `player.displayname` (empty string if not present)\n  \"uuid\": \"…\",     // mirrors `player.uuid`\n  \"player\": {\n    // data as returned by the Hypixel API\n  }\n}\n```\n\n#### Account does not exist (`/name/…` only)\n\n```http\nHTTP/1.1 404 Not Found\n...\nContent-Type: application/json\n\n{\n  \"success\": false,\n  \"error\": \"profile not found\"\n}\n```\n\n#### Account does not exist (`/uuid/…` only); Account exists, player does not exist (either endpoint)\n\n```http\nHTTP/1.1 200 OK\n...\nContent-Type: application/json\n\n{\n  \"success\": true,\n  \"fetchedAt\": \"1970-01-01T00:00:00Z\",\n  \"cached\": false\n}\n```\n\n#### Invalid request\n\n```http\nHTTP/1.1 400 Bad Request\n...\nContent-Type: application/json\n\n{\n  \"success\": false,\n  \"error\": \"…\",\n  // \"invalid type\"     request path was not /name/… or /uuid/…\n  // \"invalid uuid\"     must match /^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$/i\n  // \"invalid name\"     must match /^[a-zA-Z0-9_]{3,16}$/\n}\n```\n\n#### Invalid or missing API key\n\n```http\nHTTP/1.1 401 Unauthorized\n...\nContent-Type: application/json\n\n{\n  \"success\": false,\n  \"error\": \"unauthorized\"\n}\n```\n\n#### Hypixel API ratelimit\n\n```http\nHTTP/1.1 429 Too Many Requests\n...\nContent-Type: application/json\n\n{\n  \"success\": false,\n  \"error\": \"ratelimited, try again later\"\n}\n```\n\n#### Server error\n\n```http\nHTTP/1.1 500 Internal Server Error\n...\nContent-Type: application/json\n\n{\n  \"success\": false,\n  \"error\": \"…\"  // varies\n}\n```\n","readmeFilename":"README.md"}