@ipgeotrace/fastify 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @ipgeotrace/fastify
+
+Fastify plugin for [IPGeoTrace](https://ipgeotrace.com). Resolves the caller's location once per
+request and hands it to you on `request.geo`. Built on [`@ipgeotrace/client`](../client) — the
+secret key stays server-side.
+
+Sign up and grab your API key at [ipgeotrace.com](https://ipgeotrace.com).
+
+## Install
+
+```sh
+npm add @ipgeotrace/fastify fastify
+```
+
+## Usage
+
+```ts
+import Fastify from 'fastify';
+import { ipgeotrace, getGeo } from '@ipgeotrace/fastify';
+
+const app = Fastify({ trustProxy: true }); // so request.ip reads X-Forwarded-For behind a proxy
+
+await app.register(ipgeotrace, { apiKey: process.env.IPGEOTRACE_API_KEY! });
+
+app.get('/checkout', (request, reply) => {
+  const geo = getGeo(request);
+  const currency = geo.status === 'resolved' ? geo.value?.country?.currency ?? 'USD' : 'USD';
+  reply.send({ currency });
+});
+```
+
+The plugin is registered app-wide (wrapped with `fastify-plugin`), so `request.geo` is available in
+every route.
+
+`request.geo` (and `getGeo(request)`) is a `GeoLookup` whose `status` tells you exactly what
+happened:
+
+- `resolved` — `value` carries the data.
+- `skipped` — the caller's IP was missing, private, loopback, or link-local, so no API call was made.
+- `failed` — `error` carries the reason (`rate_limited`, `quota_exceeded`, …).
+- `not_attempted` — the plugin opted out for this request (`shouldResolve` returned false).
+
+`getGeo()` is always safe to call and returns `not_attempted` when the plugin never ran.
+
+## Skipping requests
+
+Health checks and internal endpoints should not spend lookups. Opt them out with `shouldResolve`:
+
+```ts
+await app.register(ipgeotrace, {
+  apiKey: process.env.IPGEOTRACE_API_KEY!,
+  shouldResolve: (request) => !request.url.startsWith('/health') && !request.url.startsWith('/internal'),
+});
+```
+
+Private, loopback, and link-local addresses (including IPv4-mapped IPv6) are detected locally and
+skipped without an API call or quota usage.
+
+## Choosing the caller's IP
+
+By default the plugin uses `request.ip`, which respects Fastify's `trustProxy` setting. For full
+control, supply your own selector:
+
+```ts
+await app.register(ipgeotrace, {
+  apiKey: process.env.IPGEOTRACE_API_KEY!,
+  ipSelector: (request) => (request.headers['cf-connecting-ip'] as string) ?? request.ip,
+});
+```
+
+## Configuration
+
+Pass client options through `clientOptions`, or share a pre-built client across your app:
+
+```ts
+import { IpGeoTraceClient } from '@ipgeotrace/client';
+
+// inline client options
+await app.register(ipgeotrace, {
+  apiKey: process.env.IPGEOTRACE_API_KEY!,
+  clientOptions: { cache: true, cacheTtlMs: 6 * 60 * 60_000, timeoutMs: 3_000 },
+});
+
+// or bring your own client (also usable directly in services)
+const client = new IpGeoTraceClient({ apiKey: process.env.IPGEOTRACE_API_KEY!, cache: true });
+await app.register(ipgeotrace, { client });
+```
+
+See the [`@ipgeotrace/client` README](../client) for caching, retries, timeouts, and batch lookups.

package/dist/index.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+var client = require('@ipgeotrace/client');
+var fp = require('fastify-plugin');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fp__default = /*#__PURE__*/_interopDefault(fp);
+
+// src/plugin.ts
+var plugin = async (fastify, options) => {
+  const client$1 = resolveClient(options);
+  const shouldResolve = options.shouldResolve ?? (() => true);
+  const ipSelector = options.ipSelector ?? ((req) => req.ip);
+  if (!fastify.hasRequestDecorator("geo")) {
+    fastify.decorateRequest("geo", void 0);
+  }
+  fastify.addHook("onRequest", async (req) => {
+    if (!shouldResolve(req)) {
+      req.geo = { status: "not_attempted" };
+      return;
+    }
+    const ip = ipSelector(req);
+    if (!ip || client.isPrivateOrReservedIp(ip)) {
+      req.geo = { status: "skipped" };
+      return;
+    }
+    const result = await client$1.resolve(ip);
+    req.geo = result.ok ? { status: "resolved", value: result.value } : { status: "failed", error: result.error };
+  });
+};
+var ipgeotrace = fp__default.default(plugin, {
+  fastify: ">=4.26.0 <6.0.0",
+  name: "@ipgeotrace/fastify"
+});
+function getGeo(req) {
+  return req.geo ?? { status: "not_attempted" };
+}
+function resolveClient(options) {
+  if (options.client) return options.client;
+  if (!options.apiKey) {
+    throw new Error("IPGeoTrace: pass either a client or an apiKey to the fastify plugin.");
+  }
+  return new client.IpGeoTraceClient({ apiKey: options.apiKey, ...options.clientOptions });
+}
+
+exports.getGeo = getGeo;
+exports.ipgeotrace = ipgeotrace;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts"],"names":["client","isPrivateOrReservedIp","fp","IpGeoTraceClient"],"mappings":";;;;;;;;;;AAKA,IAAM,MAAA,GAAsD,OAAO,OAAA,EAAS,OAAA,KAAY;AACtF,EAAA,MAAMA,QAAA,GAAS,cAAc,OAAO,CAAA;AACpC,EAAA,MAAM,aAAA,GAAgB,OAAA,CAAQ,aAAA,KAAkB,MAAM,IAAA,CAAA;AACtD,EAAA,MAAM,UAAA,GAAa,OAAA,CAAQ,UAAA,KAAe,CAAC,QAAwB,GAAA,CAAI,EAAA,CAAA;AAEvE,EAAA,IAAI,CAAC,OAAA,CAAQ,mBAAA,CAAoB,KAAK,CAAA,EAAG;AACvC,IAAA,OAAA,CAAQ,eAAA,CAAgB,OAAO,MAAS,CAAA;AAAA,EAC1C;AAEA,EAAA,OAAA,CAAQ,OAAA,CAAQ,WAAA,EAAa,OAAO,GAAA,KAAwB;AAC1D,IAAA,IAAI,CAAC,aAAA,CAAc,GAAG,CAAA,EAAG;AACvB,MAAA,GAAA,CAAI,GAAA,GAAM,EAAE,MAAA,EAAQ,eAAA,EAAgB;AACpC,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,EAAA,GAAK,WAAW,GAAG,CAAA;AACzB,IAAA,IAAI,CAAC,EAAA,IAAMC,4BAAA,CAAsB,EAAE,CAAA,EAAG;AACpC,MAAA,GAAA,CAAI,GAAA,GAAM,EAAE,MAAA,EAAQ,SAAA,EAAU;AAC9B,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,MAAA,GAAS,MAAMD,QAAA,CAAO,OAAA,CAAQ,EAAE,CAAA;AACtC,IAAA,GAAA,CAAI,GAAA,GAAM,MAAA,CAAO,EAAA,GACb,EAAE,QAAQ,UAAA,EAAY,KAAA,EAAO,MAAA,CAAO,KAAA,KACpC,EAAE,MAAA,EAAQ,QAAA,EAAU,KAAA,EAAO,OAAO,KAAA,EAAM;AAAA,EAC9C,CAAC,CAAA;AACH,CAAA;AAEO,IAAM,UAAA,GAAaE,oBAAG,MAAA,EAAQ;AAAA,EACnC,OAAA,EAAS,iBAAA;AAAA,EACT,IAAA,EAAM;AACR,CAAC;AAEM,SAAS,OAAO,GAAA,EAAgC;AACrD,EAAA,OAAO,GAAA,CAAI,GAAA,IAAO,EAAE,MAAA,EAAQ,eAAA,EAAgB;AAC9C;AAEA,SAAS,cAAc,OAAA,EAAoD;AACzE,EAAA,IAAI,OAAA,CAAQ,MAAA,EAAQ,OAAO,OAAA,CAAQ,MAAA;AACnC,EAAA,IAAI,CAAC,QAAQ,MAAA,EAAQ;AACnB,IAAA,MAAM,IAAI,MAAM,sEAAsE,CAAA;AAAA,EACxF;AACA,EAAA,OAAO,IAAIC,wBAAiB,EAAE,MAAA,EAAQ,QAAQ,MAAA,EAAQ,GAAG,OAAA,CAAQ,aAAA,EAAe,CAAA;AAClF","file":"index.cjs","sourcesContent":["import { IpGeoTraceClient, isPrivateOrReservedIp, type GeoLookup } from '@ipgeotrace/client';\nimport type { FastifyPluginAsync, FastifyRequest } from 'fastify';\nimport fp from 'fastify-plugin';\nimport type { IpGeoTracePluginOptions } from './types.js';\n\nconst plugin: FastifyPluginAsync<IpGeoTracePluginOptions> = async (fastify, options) => {\n  const client = resolveClient(options);\n  const shouldResolve = options.shouldResolve ?? (() => true);\n  const ipSelector = options.ipSelector ?? ((req: FastifyRequest) => req.ip);\n\n  if (!fastify.hasRequestDecorator('geo')) {\n    fastify.decorateRequest('geo', undefined);\n  }\n\n  fastify.addHook('onRequest', async (req: FastifyRequest) => {\n    if (!shouldResolve(req)) {\n      req.geo = { status: 'not_attempted' };\n      return;\n    }\n\n    const ip = ipSelector(req);\n    if (!ip || isPrivateOrReservedIp(ip)) {\n      req.geo = { status: 'skipped' };\n      return;\n    }\n\n    const result = await client.resolve(ip);\n    req.geo = result.ok\n      ? { status: 'resolved', value: result.value }\n      : { status: 'failed', error: result.error };\n  });\n};\n\nexport const ipgeotrace = fp(plugin, {\n  fastify: '>=4.26.0 <6.0.0',\n  name: '@ipgeotrace/fastify',\n});\n\nexport function getGeo(req: FastifyRequest): GeoLookup {\n  return req.geo ?? { status: 'not_attempted' };\n}\n\nfunction resolveClient(options: IpGeoTracePluginOptions): IpGeoTraceClient {\n  if (options.client) return options.client;\n  if (!options.apiKey) {\n    throw new Error('IPGeoTrace: pass either a client or an apiKey to the fastify plugin.');\n  }\n  return new IpGeoTraceClient({ apiKey: options.apiKey, ...options.clientOptions });\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,21 @@
+import { GeoLookup, IpGeoTraceClient, IpGeoTraceClientOptions } from '@ipgeotrace/client';
+export { GeoError, GeoLookup, GeoLookupStatus, GeoResponse } from '@ipgeotrace/client';
+import { FastifyRequest, FastifyPluginAsync } from 'fastify';
+
+interface IpGeoTracePluginOptions {
+    apiKey?: string;
+    client?: IpGeoTraceClient;
+    clientOptions?: Omit<IpGeoTraceClientOptions, 'apiKey'>;
+    shouldResolve?: (req: FastifyRequest) => boolean;
+    ipSelector?: (req: FastifyRequest) => string | undefined;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        geo?: GeoLookup;
+    }
+}
+
+declare const ipgeotrace: FastifyPluginAsync<IpGeoTracePluginOptions>;
+declare function getGeo(req: FastifyRequest): GeoLookup;
+
+export { type IpGeoTracePluginOptions, getGeo, ipgeotrace };

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { GeoLookup, IpGeoTraceClient, IpGeoTraceClientOptions } from '@ipgeotrace/client';
+export { GeoError, GeoLookup, GeoLookupStatus, GeoResponse } from '@ipgeotrace/client';
+import { FastifyRequest, FastifyPluginAsync } from 'fastify';
+
+interface IpGeoTracePluginOptions {
+    apiKey?: string;
+    client?: IpGeoTraceClient;
+    clientOptions?: Omit<IpGeoTraceClientOptions, 'apiKey'>;
+    shouldResolve?: (req: FastifyRequest) => boolean;
+    ipSelector?: (req: FastifyRequest) => string | undefined;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        geo?: GeoLookup;
+    }
+}
+
+declare const ipgeotrace: FastifyPluginAsync<IpGeoTracePluginOptions>;
+declare function getGeo(req: FastifyRequest): GeoLookup;
+
+export { type IpGeoTracePluginOptions, getGeo, ipgeotrace };

package/dist/index.js

@@ -0,0 +1,43 @@
+import { isPrivateOrReservedIp, IpGeoTraceClient } from '@ipgeotrace/client';
+import fp from 'fastify-plugin';
+
+// src/plugin.ts
+var plugin = async (fastify, options) => {
+  const client = resolveClient(options);
+  const shouldResolve = options.shouldResolve ?? (() => true);
+  const ipSelector = options.ipSelector ?? ((req) => req.ip);
+  if (!fastify.hasRequestDecorator("geo")) {
+    fastify.decorateRequest("geo", void 0);
+  }
+  fastify.addHook("onRequest", async (req) => {
+    if (!shouldResolve(req)) {
+      req.geo = { status: "not_attempted" };
+      return;
+    }
+    const ip = ipSelector(req);
+    if (!ip || isPrivateOrReservedIp(ip)) {
+      req.geo = { status: "skipped" };
+      return;
+    }
+    const result = await client.resolve(ip);
+    req.geo = result.ok ? { status: "resolved", value: result.value } : { status: "failed", error: result.error };
+  });
+};
+var ipgeotrace = fp(plugin, {
+  fastify: ">=4.26.0 <6.0.0",
+  name: "@ipgeotrace/fastify"
+});
+function getGeo(req) {
+  return req.geo ?? { status: "not_attempted" };
+}
+function resolveClient(options) {
+  if (options.client) return options.client;
+  if (!options.apiKey) {
+    throw new Error("IPGeoTrace: pass either a client or an apiKey to the fastify plugin.");
+  }
+  return new IpGeoTraceClient({ apiKey: options.apiKey, ...options.clientOptions });
+}
+
+export { getGeo, ipgeotrace };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts"],"names":[],"mappings":";;;;AAKA,IAAM,MAAA,GAAsD,OAAO,OAAA,EAAS,OAAA,KAAY;AACtF,EAAA,MAAM,MAAA,GAAS,cAAc,OAAO,CAAA;AACpC,EAAA,MAAM,aAAA,GAAgB,OAAA,CAAQ,aAAA,KAAkB,MAAM,IAAA,CAAA;AACtD,EAAA,MAAM,UAAA,GAAa,OAAA,CAAQ,UAAA,KAAe,CAAC,QAAwB,GAAA,CAAI,EAAA,CAAA;AAEvE,EAAA,IAAI,CAAC,OAAA,CAAQ,mBAAA,CAAoB,KAAK,CAAA,EAAG;AACvC,IAAA,OAAA,CAAQ,eAAA,CAAgB,OAAO,MAAS,CAAA;AAAA,EAC1C;AAEA,EAAA,OAAA,CAAQ,OAAA,CAAQ,WAAA,EAAa,OAAO,GAAA,KAAwB;AAC1D,IAAA,IAAI,CAAC,aAAA,CAAc,GAAG,CAAA,EAAG;AACvB,MAAA,GAAA,CAAI,GAAA,GAAM,EAAE,MAAA,EAAQ,eAAA,EAAgB;AACpC,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,EAAA,GAAK,WAAW,GAAG,CAAA;AACzB,IAAA,IAAI,CAAC,EAAA,IAAM,qBAAA,CAAsB,EAAE,CAAA,EAAG;AACpC,MAAA,GAAA,CAAI,GAAA,GAAM,EAAE,MAAA,EAAQ,SAAA,EAAU;AAC9B,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,MAAA,GAAS,MAAM,MAAA,CAAO,OAAA,CAAQ,EAAE,CAAA;AACtC,IAAA,GAAA,CAAI,GAAA,GAAM,MAAA,CAAO,EAAA,GACb,EAAE,QAAQ,UAAA,EAAY,KAAA,EAAO,MAAA,CAAO,KAAA,KACpC,EAAE,MAAA,EAAQ,QAAA,EAAU,KAAA,EAAO,OAAO,KAAA,EAAM;AAAA,EAC9C,CAAC,CAAA;AACH,CAAA;AAEO,IAAM,UAAA,GAAa,GAAG,MAAA,EAAQ;AAAA,EACnC,OAAA,EAAS,iBAAA;AAAA,EACT,IAAA,EAAM;AACR,CAAC;AAEM,SAAS,OAAO,GAAA,EAAgC;AACrD,EAAA,OAAO,GAAA,CAAI,GAAA,IAAO,EAAE,MAAA,EAAQ,eAAA,EAAgB;AAC9C;AAEA,SAAS,cAAc,OAAA,EAAoD;AACzE,EAAA,IAAI,OAAA,CAAQ,MAAA,EAAQ,OAAO,OAAA,CAAQ,MAAA;AACnC,EAAA,IAAI,CAAC,QAAQ,MAAA,EAAQ;AACnB,IAAA,MAAM,IAAI,MAAM,sEAAsE,CAAA;AAAA,EACxF;AACA,EAAA,OAAO,IAAI,iBAAiB,EAAE,MAAA,EAAQ,QAAQ,MAAA,EAAQ,GAAG,OAAA,CAAQ,aAAA,EAAe,CAAA;AAClF","file":"index.js","sourcesContent":["import { IpGeoTraceClient, isPrivateOrReservedIp, type GeoLookup } from '@ipgeotrace/client';\nimport type { FastifyPluginAsync, FastifyRequest } from 'fastify';\nimport fp from 'fastify-plugin';\nimport type { IpGeoTracePluginOptions } from './types.js';\n\nconst plugin: FastifyPluginAsync<IpGeoTracePluginOptions> = async (fastify, options) => {\n  const client = resolveClient(options);\n  const shouldResolve = options.shouldResolve ?? (() => true);\n  const ipSelector = options.ipSelector ?? ((req: FastifyRequest) => req.ip);\n\n  if (!fastify.hasRequestDecorator('geo')) {\n    fastify.decorateRequest('geo', undefined);\n  }\n\n  fastify.addHook('onRequest', async (req: FastifyRequest) => {\n    if (!shouldResolve(req)) {\n      req.geo = { status: 'not_attempted' };\n      return;\n    }\n\n    const ip = ipSelector(req);\n    if (!ip || isPrivateOrReservedIp(ip)) {\n      req.geo = { status: 'skipped' };\n      return;\n    }\n\n    const result = await client.resolve(ip);\n    req.geo = result.ok\n      ? { status: 'resolved', value: result.value }\n      : { status: 'failed', error: result.error };\n  });\n};\n\nexport const ipgeotrace = fp(plugin, {\n  fastify: '>=4.26.0 <6.0.0',\n  name: '@ipgeotrace/fastify',\n});\n\nexport function getGeo(req: FastifyRequest): GeoLookup {\n  return req.geo ?? { status: 'not_attempted' };\n}\n\nfunction resolveClient(options: IpGeoTracePluginOptions): IpGeoTraceClient {\n  if (options.client) return options.client;\n  if (!options.apiKey) {\n    throw new Error('IPGeoTrace: pass either a client or an apiKey to the fastify plugin.');\n  }\n  return new IpGeoTraceClient({ apiKey: options.apiKey, ...options.clientOptions });\n}\n"]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ipgeotrace/fastify",
+  "version": "0.1.0",
+  "description": "Fastify plugin for IPGeoTrace. Resolves the caller's location once per request and exposes it on request.geo.",
+  "keywords": [
+    "ipgeotrace",
+    "geolocation",
+    "geoip",
+    "fastify",
+    "plugin",
+    "typescript"
+  ],
+  "license": "MIT",
+  "homepage": "https://ipgeotrace.com",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "fastify-plugin": "^4.5.1 || ^5.0.1",
+    "@ipgeotrace/client": "0.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^4.26.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "fastify": "^5.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}