{"_id":"@colyseus/geoip","_rev":"6-45bfc7c3cba19517137c3051a8a40b4f","name":"@colyseus/geoip","dist-tags":{"next":"0.18.1","latest":"0.18.4"},"versions":{"0.18.0":{"name":"@colyseus/geoip","version":"0.18.0","keywords":["colyseus","geoip","country","maxmind","geolite2","db-ip"],"author":{"name":"Endel Dreyer"},"license":"MIT","_id":"@colyseus/geoip@0.18.0","maintainers":[{"name":"endel","email":"endel.dreyer@gmail.com"}],"homepage":"https://colyseus.io/","bugs":{"url":"https://github.com/colyseus/colyseus/issues"},"dist":{"shasum":"49a4d61966b640bc3b0f629a43ed513fabd349ee","tarball":"https://registry.npmjs.org/@colyseus/geoip/-/geoip-0.18.0.tgz","fileCount":33,"integrity":"sha512-FjtqBo3DmIB+Y2rotfsmlQlf3G3RFb7koAE7Do1SheuQoTOh08siPs1+9KffiSVPa+r/LX9e4lBUlbiI/dQgGg==","signatures":[{"sig":"MEUCICApNT8t3Z8RgHlmlX2p0TY+04rhViCLfHzJj41Q38VXAiEA3ePoF0+kazbfWUEOc7j6EBXusaGrUB+N5fW80BPuQig=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":103170},"main":"./build/index.cjs","type":"module","_from":"file:colyseus-geoip-0.18.0.tgz","input":"./src/index.ts","module":"./src/index.ts","engines":{"node":">= 22.x"},"exports":{".":{"types":"./build/index.d.ts","import":"./build/index.mjs","@source":"./src/index.ts","require":"./build/index.cjs"},"./*":{"types":"./build/*.d.ts","import":"./build/*.mjs","@source":"./src/*.ts","require":"./build/*.cjs"}},"funding":"https://github.com/sponsors/endel","scripts":{"test":"mocha test/**.test.ts --exit --timeout 15000"},"typings":"./build/index.d.ts","_npmUser":{"name":"endel","email":"endel.dreyer@gmail.com"},"_resolved":"/tmp/4ec0a223c3d77340f6618b7cdef2c291/colyseus-geoip-0.18.0.tgz","_integrity":"sha512-FjtqBo3DmIB+Y2rotfsmlQlf3G3RFb7koAE7Do1SheuQoTOh08siPs1+9KffiSVPa+r/LX9e4lBUlbiI/dQgGg==","repository":{"url":"git://github.com/colyseus/colyseus.git","type":"git"},"_npmVersion":"10.9.8","description":"GeoIP country detection plugin for Colyseus rooms.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"maxmind":"^5.0.0"},"publishConfig":{"tag":"next","access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"@colyseus/core":"^0.18.0"},"_npmOperationalInternal":{"tmp":"tmp/geoip_0.18.0_1779476087432_0.4887064139480912","host":"s3://npm-registry-packages-npm-production"}},"0.18.1":{"name":"@colyseus/geoip","version":"0.18.1","keywords":["colyseus","geoip","country","maxmind","geolite2","db-ip"],"author":{"name":"Endel Dreyer"},"license":"MIT","_id":"@colyseus/geoip@0.18.1","maintainers":[{"name":"endel","email":"endel.dreyer@gmail.com"}],"homepage":"https://colyseus.io/","bugs":{"url":"https://github.com/colyseus/colyseus/issues"},"dist":{"shasum":"cad31b6a4b774630fb988d7529917b2329cb5e92","tarball":"https://registry.npmjs.org/@colyseus/geoip/-/geoip-0.18.1.tgz","fileCount":33,"integrity":"sha512-Dz5JcIc9F11AzZV3ee/V+6xyVob6t9EIqg7OCpLJ9VQgvs0nZYMz/uOsA5sISa/ivx+DIfyiMXq4667oHI3vWQ==","signatures":[{"sig":"MEUCIQDqrAhGy2nFunTcpBr8zetljMilBV37UtbCjXZBSVNFmgIgEYVNBR4ckgx+WNJhcG1twxawmxaXuvw84vGMt+5w1MY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":103170},"main":"./build/index.cjs","type":"module","_from":"file:colyseus-geoip-0.18.1.tgz","input":"./src/index.ts","module":"./src/index.ts","engines":{"node":">= 22.x"},"exports":{".":{"types":"./build/index.d.ts","import":"./build/index.mjs","@source":"./src/index.ts","require":"./build/index.cjs"},"./*":{"types":"./build/*.d.ts","import":"./build/*.mjs","@source":"./src/*.ts","require":"./build/*.cjs"}},"funding":"https://github.com/sponsors/endel","scripts":{"test":"mocha test/**.test.ts --exit --timeout 15000"},"typings":"./build/index.d.ts","_npmUser":{"name":"endel","email":"endel.dreyer@gmail.com"},"_resolved":"/tmp/5c482c99519cce928a63d22314acc118/colyseus-geoip-0.18.1.tgz","_integrity":"sha512-Dz5JcIc9F11AzZV3ee/V+6xyVob6t9EIqg7OCpLJ9VQgvs0nZYMz/uOsA5sISa/ivx+DIfyiMXq4667oHI3vWQ==","repository":{"url":"git://github.com/colyseus/colyseus.git","type":"git"},"_npmVersion":"10.9.8","description":"GeoIP country detection plugin for Colyseus rooms.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"maxmind":"^5.0.0"},"publishConfig":{"tag":"next","access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","peerDependencies":{"@colyseus/core":"^0.18.1"},"_npmOperationalInternal":{"tmp":"tmp/geoip_0.18.1_1784622960581_0.976460508837238","host":"s3://npm-registry-packages-npm-production"}},"0.18.2":{"name":"@colyseus/geoip","version":"0.18.2","keywords":["colyseus","geoip","country","maxmind","geolite2","db-ip"],"author":{"name":"Endel Dreyer"},"license":"MIT","_id":"@colyseus/geoip@0.18.2","maintainers":[{"name":"endel","email":"endel.dreyer@gmail.com"}],"homepage":"https://colyseus.io/","bugs":{"url":"https://github.com/colyseus/colyseus/issues"},"dist":{"shasum":"8ae8eb8d2abc1c75e145f70d687c3ff9a59202a3","tarball":"https://registry.npmjs.org/@colyseus/geoip/-/geoip-0.18.2.tgz","fileCount":33,"integrity":"sha512-EorWdvpmvZkMFFZaIc3uoZDvCvEJHqfUmhyUFepHdAOr6jIAt1gvRNpfHLy4z8B/ELdlKC/cwwJO6G7snDr8fA==","signatures":[{"sig":"MEUCIQClnQTzOiSOTtQuu+kp7tgcz+Wfp85iOkrSMet9wkwY6QIgZnxgCIu+rrKi5V9IlQnggiaBlaA1OKPuXBNO9s7+5AU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":102576},"main":"./build/index.cjs","type":"module","_from":"file:colyseus-geoip-0.18.2.tgz","input":"./src/index.ts","module":"./src/index.ts","engines":{"node":">= 22.x"},"exports":{".":{"types":"./build/index.d.ts","import":"./build/index.mjs","@source":"./src/index.ts","require":"./build/index.cjs"},"./*":{"types":"./build/*.d.ts","import":"./build/*.mjs","@source":"./src/*.ts","require":"./build/*.cjs"}},"funding":"https://github.com/sponsors/endel","scripts":{"test":"mocha test/**.test.ts --exit --timeout 15000"},"typings":"./build/index.d.ts","_npmUser":{"name":"endel","email":"endel.dreyer@gmail.com"},"_resolved":"/tmp/1f5486921e95588dac84552cc78fde5c/colyseus-geoip-0.18.2.tgz","_integrity":"sha512-EorWdvpmvZkMFFZaIc3uoZDvCvEJHqfUmhyUFepHdAOr6jIAt1gvRNpfHLy4z8B/ELdlKC/cwwJO6G7snDr8fA==","repository":{"url":"git://github.com/colyseus/colyseus.git","type":"git"},"_npmVersion":"10.9.8","description":"GeoIP country detection plugin for Colyseus rooms.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"maxmind":"^5.0.0"},"publishConfig":{"tag":"next","access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"@colyseus/core":"^0.18.8"},"_npmOperationalInternal":{"tmp":"tmp/geoip_0.18.2_1787703556362_0.5545387747744612","host":"s3://npm-registry-packages-npm-production"}},"0.18.3":{"name":"@colyseus/geoip","version":"0.18.3","keywords":["colyseus","geoip","country","maxmind","geolite2","db-ip"],"author":{"name":"Endel Dreyer"},"license":"MIT","_id":"@colyseus/geoip@0.18.3","maintainers":[{"name":"endel","email":"endel.dreyer@gmail.com"}],"homepage":"https://colyseus.io/","bugs":{"url":"https://github.com/colyseus/colyseus/issues"},"dist":{"shasum":"c9afea1f414e8661f6ed0115e5e4837c00a92821","tarball":"https://registry.npmjs.org/@colyseus/geoip/-/geoip-0.18.3.tgz","fileCount":39,"integrity":"sha512-yxakZ3OjfTWHu+iyqGWILnmLrGLa0F4AsZCO9GoR54OvAlb4JrTtcu8mwqFMTCm56bEmQWANj+5qXTNLCH8OWw==","signatures":[{"sig":"MEYCIQCj1buQ7lHLRoCQP6ViLhuUQ/IBTxhPA5W5aqXttJFMTwIhAL1mNSRcj8lmtCl7PJR7ym2+4ry19fotucXIP7ztO2I7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCsP7JA+XdQv2FFXB2+R433nRn+I2HpEpBKyrboot0p/wIgaZ9UFcuScPykkdptPVDXvpoNDMXHP8H1b1K9v4ITWYM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":125882},"main":"./build/index.cjs","type":"module","_from":"file:colyseus-geoip-0.18.3.tgz","input":"./src/index.ts","module":"./src/index.ts","engines":{"node":">= 22.x"},"exports":{".":{"types":"./build/index.d.ts","import":"./build/index.mjs","@source":"./src/index.ts","require":"./build/index.cjs"},"./*":{"types":"./build/*.d.ts","import":"./build/*.mjs","@source":"./src/*.ts","require":"./build/*.cjs"}},"funding":"https://github.com/sponsors/endel","scripts":{"test":"mocha test/**.test.ts --exit --timeout 15000"},"typings":"./build/index.d.ts","_npmUser":{"name":"endel","email":"endel.dreyer@gmail.com"},"_resolved":"/tmp/8bf1a9697b401810aadb55e5b058f2c3/colyseus-geoip-0.18.3.tgz","_integrity":"sha512-yxakZ3OjfTWHu+iyqGWILnmLrGLa0F4AsZCO9GoR54OvAlb4JrTtcu8mwqFMTCm56bEmQWANj+5qXTNLCH8OWw==","repository":{"url":"git://github.com/colyseus/colyseus.git","type":"git"},"_npmVersion":"10.9.8","description":"GeoIP country detection plugin for Colyseus rooms.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"maxmind":"^5.0.0"},"publishConfig":{"tag":"next","access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"@colyseus/core":"^0.18.15"},"_npmOperationalInternal":{"tmp":"tmp/geoip_0.18.3_1790020029380_0.9795454629823461","host":"s3://npm-registry-packages-npm-production"}},"0.18.4":{"_id":"@colyseus/geoip@0.18.4","bugs":{"url":"https://github.com/colyseus/colyseus/issues"},"dist":{"shasum":"bb71760b640cbf1acaf40ef8c070d861e636a0a6","tarball":"https://registry.npmjs.org/@colyseus/geoip/-/geoip-0.18.4.tgz","fileCount":39,"integrity":"sha512-MSbKYMo5oa5VsgpssNUPIh0REqCiVw7K7FBG+n0Tv6thWAPCb5Oh4N3Dux6jpLE+Uq0tAG2XZ/g6SINX8r/rHQ==","signatures":[{"sig":"MEQCIFIGvcY1Ou3fq5FvxLlTBwLJ8EsGaaREkrGAQxurbn1IAiBUmYLNGXOU0b94vGNCQeTZ9krQz3+Et+Qkr4rJ5owlrA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC3XAAvE/YKtRCekIPn2djElgHx/gsiBodiS62RtFeH8gIgFe8asZpWfluTpj1LQySODzIzBBW94MPUP5TxMYRVLUg="}],"unpackedSize":125962},"main":"./build/index.cjs","name":"@colyseus/geoip","type":"module","_from":"file:colyseus-geoip-0.18.4.tgz","input":"./src/index.ts","author":{"name":"Endel Dreyer"},"module":"./src/index.ts","engines":{"node":">= 22.x"},"exports":{".":{"types":"./build/index.d.ts","import":"./build/index.mjs","@source":"./src/index.ts","require":"./build/index.cjs","module-sync":"./build/index.mjs"},"./*":{"types":"./build/*.d.ts","import":"./build/*.mjs","@source":"./src/*.ts","require":"./build/*.cjs","module-sync":"./build/*.mjs"}},"funding":"https://github.com/sponsors/endel","license":"MIT","scripts":{"test":"mocha test/**.test.ts --exit --timeout 15000"},"typings":"./build/index.d.ts","version":"0.18.4","_npmUser":{"name":"endel","email":"endel.dreyer@gmail.com"},"homepage":"https://colyseus.io/","keywords":["colyseus","geoip","country","maxmind","geolite2","db-ip"],"_resolved":"/tmp/777770cf3dfda661d053151cc7831607/colyseus-geoip-0.18.4.tgz","_integrity":"sha512-MSbKYMo5oa5VsgpssNUPIh0REqCiVw7K7FBG+n0Tv6thWAPCb5Oh4N3Dux6jpLE+Uq0tAG2XZ/g6SINX8r/rHQ==","repository":{"url":"git://github.com/colyseus/colyseus.git","type":"git"},"_npmVersion":"10.9.8","description":"GeoIP country detection plugin for Colyseus rooms.","directories":{},"maintainers":[{"name":"endel","email":"endel.dreyer@gmail.com"}],"_nodeVersion":"22.23.2","dependencies":{"maxmind":"^5.0.0"},"publishConfig":{"tag":"next","access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"@colyseus/core":"^0.18.16"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/geoip_0.18.4_1790140954389_0.9250788575265798"}}},"time":{"created":"2026-05-22T18:54:47.258Z","modified":"2026-09-23T05:22:34.675Z","0.18.0":"2026-05-22T18:54:47.583Z","0.18.1":"2026-07-21T08:36:00.711Z","0.18.2":"2026-08-26T00:19:16.510Z","0.18.3":"2026-09-21T19:47:09.469Z","0.18.4":"2026-09-23T05:22:34.480Z"},"bugs":{"url":"https://github.com/colyseus/colyseus/issues"},"author":{"name":"Endel Dreyer"},"license":"MIT","homepage":"https://colyseus.io/","keywords":["colyseus","geoip","country","maxmind","geolite2","db-ip"],"repository":{"url":"git://github.com/colyseus/colyseus.git","type":"git"},"description":"GeoIP country detection plugin for Colyseus rooms.","maintainers":[{"name":"endel","email":"endel.dreyer@gmail.com"}],"readme":"# @colyseus/geoip\n\nCountry-level GeoIP plugin for Colyseus rooms. Resolves the client's IP at\nauth time and attaches `client.geoip` before `onJoin` runs.\n\n```ts\nimport { Room, definePlugins } from \"@colyseus/core\";\nimport { GeoIPPlugin } from \"@colyseus/geoip\";\n\nclass MyRoom extends Room {\n  plugins = definePlugins([\n    new GeoIPPlugin({ dbPath: \"./GeoLite2-Country.mmdb\" }),\n  ]);\n\n  async onJoin(client) {\n    console.log(client.geoip);\n    // { isoCode: \"BR\", name: \"Brazil\", continent: \"SA\", isInEU: false }\n  }\n}\n```\n\n`client.geoip` is `undefined` for unresolvable IPs (loopback, RFC1918,\nIPv6 link-local, or simply absent from the database). Lookup failures\nnever block the join.\n\n## Database delivery modes\n\nThe plugin reads any [MMDB](https://maxmind.github.io/MaxMind-DB/) file —\nthe binary format shared by MaxMind GeoLite2 and DB-IP Lite. Three ways\nto point it at one:\n\n### 1. `dbPath` — bring your own file\n\n```ts\nnew GeoIPPlugin({ dbPath: \"/var/lib/geoip/GeoLite2-Country.mmdb\" })\n```\n\nUse this with MaxMind's [`geoipupdate`](https://github.com/maxmind/geoipupdate)\ncron, a custom build step that fetches DB-IP, or any other workflow you\nalready have.\n\n### 2. `accountId` + `licenseKey` — auto-fetch from MaxMind\n\n```ts\nnew GeoIPPlugin({\n  accountId: process.env.MAXMIND_ACCOUNT_ID,\n  licenseKey: process.env.MAXMIND_LICENSE_KEY,\n  // optional:\n  cacheDir: \"/var/cache/colyseus-geoip\",\n  refreshIntervalMs: 7 * 24 * 60 * 60 * 1000, // weekly\n})\n```\n\nDownloads `GeoLite2-Country.mmdb` under your MaxMind credentials on the\nfirst boot, caches to disk, and refreshes weekly. Sign up at\n<https://www.maxmind.com/en/geolite2/signup> to get credentials.\n\n### 3. DB-IP Lite — no configuration\n\n```ts\nnew GeoIPPlugin()\n\n// optional:\nnew GeoIPPlugin({ cacheDir: \"/var/cache/colyseus-geoip\" })\n```\n\nDownloads DB-IP's Lite Country database from db-ip.com on the first boot\n— no account, no credentials — and caches it to disk. DB-IP publishes a\nnew snapshot on the 1st of each month; the plugin checks daily and picks\nit up when it lands, falling back to last month's until it does.\n\nThe database is fetched rather than shipped inside this package: ~4 MB\nover the wire, 8 MB on disk, and only for the people who use this mode.\nIt needs outbound network access on the first boot — in an air-gapped\ndeployment, use mode 1 with a file you place yourself.\n\n## Licensing and attribution\n\nThis plugin reads two independently-licensed databases. **What you owe\ndepends on which mode you use.**\n\n### MaxMind GeoLite2 (modes 1 & 2)\n\nGeoLite2 data is provided under the\n[GeoLite2 EULA](https://www.maxmind.com/en/geolite2/eula). Key terms:\n\n- Free for use under your MaxMind account, including commercial use.\n- **Cannot be redistributed**; each user must download under their own\n  credentials. The plugin does not bundle MaxMind data.\n- Cannot be used for FCRA-regulated decisions (credit, insurance,\n  employment, government benefits).\n- Attribution required if you expose the data: *\"This product includes\n  GeoLite2 data created by MaxMind, available from\n  <https://www.maxmind.com>.\"*\n\n### DB-IP Lite (mode 3)\n\nDB-IP's Lite databases are licensed under\n[Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/).\nThis package does not redistribute them — mode 3 downloads the file from\ndb-ip.com onto your machine — so the attribution obligation is yours as\nthe operator, not ours:\n\n> *IP-to-country data from DB-IP.com, available under CC BY 4.0 from\n> <https://db-ip.com/db/lite.php>.*\n\nDB-IP asks that web applications displaying results from the database\nlink back to db-ip.com. If your game surfaces country information to\nplayers, use their suggested credit:\n\n```html\n<a href=\"https://db-ip.com\">IP Geolocation by DB-IP</a>\n```\n\n## Privacy\n\nThe plugin derives country from the client's IP. The IP is already\nvisible to your server; the resolved country is the same class of\npersonal data and should be treated as such under GDPR/CCPA/etc. If you\npersist `client.geoip` beyond the session, disclose it in your privacy\npolicy.\n\n## Manually testing the auto-downloader\n\n`AutoDownloader` is exercised by a standalone script rather than the\nmocha suite — it needs live MaxMind credentials and network access.\n\n```sh\nMAXMIND_ACCOUNT_ID=... MAXMIND_LICENSE_KEY=... \\\n  pnpm tsx scripts/test-autodownloader.ts\n\n# Exercise the cross-process race fix by forking N peers:\nMAXMIND_ACCOUNT_ID=... MAXMIND_LICENSE_KEY=... \\\n  pnpm tsx scripts/test-autodownloader.ts --force --concurrent 4\n```\n\nThe `--concurrent` mode forks N child processes that all call `fetch()`\nagainst the same cache directory, then asserts every child ended up with\nan identical sha256 — verifying that PID-scoped temp paths and the\nrecheck-before-rename keep peers from clobbering each other's writes.\n","readmeFilename":"README.md"}