@0xzahed/geotrack-client

TypeScript client for consuming a django-geotrack backend from Next.js / React apps.

The Django app records IP-derived location (country / division / district / city) on every user login automatically — no browser permission popup needed. This package is the frontend half: fetch that data back and display it.

Install

npm install @0xzahed/geotrack-client

Works with plain fetch (Node 18+, browsers) — React is only needed if you use the optional useLoginLocation hook.

Quick start

import { GeotrackClient, formatLocation } from "@0xzahed/geotrack-client";

const client = new GeotrackClient({
  baseUrl: "https://your-django-api.com/api/geotrack",
  getAuthHeaders: () => ({
    Authorization: `Bearer ${yourAccessToken}`,
  }),
});

const latest = await client.getLatestLocation();
console.log(formatLocation(latest)); // "Dhaka, Dhaka Division, Bangladesh"

React hook

"use client";
import { GeotrackClient } from "@0xzahed/geotrack-client";
import { useLoginLocation } from "@0xzahed/geotrack-client/react";

const client = new GeotrackClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL + "/api/geotrack",
  getAuthHeaders: () => ({ Authorization: `Bearer ${getToken()}` }),
});

export default function LastLoginBadge() {
  const { location, loading, error } = useLoginLocation(client);

  if (loading) return <span>Loading location…</span>;
  if (error) return null;

  return (
    <span>
      Last login from {location?.city}, {location?.division}, {location?.country}
    </span>
  );
}

API

new GeotrackClient(options)

| Option | Type | Description | |---|---|---| | baseUrl | string | Base URL of the geotrack API, e.g. https://api.example.com/api/geotrack | | getAuthHeaders | () => Record<string, string> | Optional. Called per request — return auth headers | | fetchImpl | typeof fetch | Optional. Custom fetch implementation (defaults to global fetch) |

Methods

| Method | Returns | Endpoint | |---|---|---| | getLatestLocation() | Promise<LoginLocation> | GET /latest-location/ | | getLoginHistory() | Promise<{ results: LoginLocation[]; count: number }> | GET /login-history/ |

formatLocation(loc)

Joins city, division, country into a readable string — "Dhaka, Dhaka Division, Bangladesh", or "Unknown location" when empty.

LoginLocation

interface LoginLocation {
  id: number;
  ip_address: string;
  country: string | null;
  country_code: string | null;
  division: string | null;   // state / region
  district: string | null;
  city: string | null;
  latitude: number | null;
  longitude: number | null;
  user_agent: string | null;
  created_at: string;        // ISO 8601
}

Both endpoints require authentication (IsAuthenticated on the Django side) — pass credentials via getAuthHeaders.

Dual ESM + CJS

Ships both module formats — import gets ESM (dist/esm/), require gets CommonJS (dist/). No configuration needed; works with Next.js, Vite, webpack, and plain Node.

Backend

Requires the companion Django app: https://github.com/0xzahed/django-geotrack

License

MIT