@sanvika/geolocation 0.1.0 → 0.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sanvika/geolocation",
-  "version": "0.1.0",
-  "description": "Sanvika ecosystem geolocation SDK — server-side IP lookup (ip-api.com) + client-side browser geolocation with cache/IP fallback",
+  "version": "0.2.1",
+  "description": "Sanvika ecosystem geolocation SDK — IP lookup, browser geolocation, reverse geocoding (lat/lng → Indian state/city), Indian states constants",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
@@ -14,10 +14,16 @@
     "src",
     "README.md"
   ],
-  "peerDependencies": {
-    "@sanvika/logger": ">=0.1"
+  "dependencies": {
+    "@sanvika/logger": ">=0.2"
   },
-  "keywords": ["sanvika", "geolocation", "ip", "location", "india"],
+  "keywords": [
+    "sanvika",
+    "geolocation",
+    "ip",
+    "location",
+    "india"
+  ],
   "author": "Sanvika Production",
   "license": "UNLICENSED",
   "repository": {
@@ -27,4 +33,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/index.js

@@ -4,3 +4,15 @@
 // Client exports: import from "@sanvika/geolocation/client"
 
 export { getLocationFromIp, clearLocationCache, isPrivateIp } from "./server/index.js";
+export {
+  detectStateFromCoordinates,
+  isUserInTargetStates,
+  clearStateCache,
+  getStateCacheStats,
+  INDIAN_STATES,
+  INDIAN_UNION_TERRITORIES,
+  ALL_INDIAN_REGIONS,
+  STATE_NAME_ALIASES,
+  normalizeStateName,
+  isValidIndianState,
+} from "./server/index.js";

package/src/server/index.js

@@ -1,5 +1,22 @@
 // packages/sanvika-geolocation-sdk/src/server/index.js
 // Server-side IP geolocation via ip-api.com (free, no API key, 45 req/min)
+// + Reverse geocoding: lat/lng → Indian state/city via Google Geocoding API
+
+export {
+  detectStateFromCoordinates,
+  isUserInTargetStates,
+  clearStateCache,
+  getStateCacheStats,
+} from "./stateDetection.js";
+
+export {
+  INDIAN_STATES,
+  INDIAN_UNION_TERRITORIES,
+  ALL_INDIAN_REGIONS,
+  STATE_NAME_ALIASES,
+  normalizeStateName,
+  isValidIndianState,
+} from "./india.js";
 
 import { createLogger } from "@sanvika/logger";
 

package/src/server/india.js

@@ -0,0 +1,46 @@
+// Official Indian States and Union Territories
+// Source: https://en.wikipedia.org/wiki/States_and_union_territories_of_India
+
+export const INDIAN_STATES = [
+  "Andhra Pradesh", "Arunachal Pradesh", "Assam", "Bihar", "Chhattisgarh",
+  "Goa", "Gujarat", "Haryana", "Himachal Pradesh", "Jharkhand", "Karnataka",
+  "Kerala", "Madhya Pradesh", "Maharashtra", "Manipur", "Meghalaya", "Mizoram",
+  "Nagaland", "Odisha", "Punjab", "Rajasthan", "Sikkim", "Tamil Nadu",
+  "Telangana", "Tripura", "Uttar Pradesh", "Uttarakhand", "West Bengal",
+];
+
+export const INDIAN_UNION_TERRITORIES = [
+  "Andaman and Nicobar Islands", "Chandigarh",
+  "Dadra and Nagar Haveli and Daman and Diu", "Delhi",
+  "Jammu and Kashmir", "Ladakh", "Lakshadweep", "Puducherry",
+];
+
+export const ALL_INDIAN_REGIONS = [...INDIAN_STATES, ...INDIAN_UNION_TERRITORIES].sort();
+
+// Maps Google Geocoding API variations → official name
+export const STATE_NAME_ALIASES = {
+  "Orissa": "Odisha",
+  "Uttaranchal": "Uttarakhand",
+  "NCT of Delhi": "Delhi",
+  "National Capital Territory of Delhi": "Delhi",
+  "Pondicherry": "Puducherry",
+  "Dadra and Nagar Haveli": "Dadra and Nagar Haveli and Daman and Diu",
+  "Daman and Diu": "Dadra and Nagar Haveli and Daman and Diu",
+  "Jammu & Kashmir": "Jammu and Kashmir",
+  "Andaman & Nicobar Islands": "Andaman and Nicobar Islands",
+};
+
+export function normalizeStateName(stateName) {
+  if (!stateName || typeof stateName !== "string") return null;
+  const trimmed = stateName.trim();
+  const direct = ALL_INDIAN_REGIONS.find((s) => s.toLowerCase() === trimmed.toLowerCase());
+  if (direct) return direct;
+  const aliasKey = Object.keys(STATE_NAME_ALIASES).find(
+    (k) => k.toLowerCase() === trimmed.toLowerCase()
+  );
+  return aliasKey ? STATE_NAME_ALIASES[aliasKey] : null;
+}
+
+export function isValidIndianState(stateName) {
+  return normalizeStateName(stateName) !== null;
+}

package/src/server/stateDetection.js

@@ -0,0 +1,112 @@
+// Reverse geocoding: lat/lng → Indian state + city via Google Geocoding API
+// Supports GOOGLE_MAPS_API_KEY (server-safe) or NEXT_PUBLIC_GOOGLE_MAPS_API_KEY (Next.js)
+
+import { createLogger } from "@sanvika/logger";
+import { normalizeStateName } from "./india.js";
+
+const logger = createLogger({ namespace: "SanvikaGeolocation.StateDetection" });
+
+// In-memory cache — key: "lat_lng" rounded to 2dp (~1.1km accuracy)
+const stateCache = new Map();
+const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours
+
+function getCacheKey(lat, lng) {
+  return `${Math.round(lat * 100) / 100}_${Math.round(lng * 100) / 100}`;
+}
+
+function getApiKey() {
+  return (
+    (typeof process !== "undefined" && process.env?.GOOGLE_MAPS_API_KEY) ||
+    (typeof process !== "undefined" && process.env?.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY) ||
+    null
+  );
+}
+
+export async function detectStateFromCoordinates(latitude, longitude) {
+  const lat = typeof latitude === "string" ? parseFloat(latitude) : latitude;
+  const lng = typeof longitude === "string" ? parseFloat(longitude) : longitude;
+
+  if (!lat || !lng || !Number.isFinite(lat) || !Number.isFinite(lng)) {
+    logger.warn("Invalid coordinates", { latitude, longitude });
+    return { state: null, city: null, fromCache: false };
+  }
+
+  const key = getCacheKey(lat, lng);
+  const cached = stateCache.get(key);
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+    return { state: cached.state, city: cached.city, fromCache: true };
+  }
+
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    logger.error("Google Maps API key not configured (set GOOGLE_MAPS_API_KEY or NEXT_PUBLIC_GOOGLE_MAPS_API_KEY)");
+    return { state: null, city: null, fromCache: false };
+  }
+
+  try {
+    const url = new URL("https://maps.googleapis.com/maps/api/geocode/json");
+    url.searchParams.set("latlng", `${lat},${lng}`);
+    url.searchParams.set("key", apiKey);
+    url.searchParams.set("result_type", "administrative_area_level_1|locality");
+
+    const res = await fetch(url.toString(), {
+      signal: AbortSignal.timeout(5000),
+    });
+
+    if (!res.ok) throw new Error(`Geocoding API returned ${res.status}`);
+
+    const data = await res.json();
+
+    if (data.status !== "OK") {
+      logger.warn("Geocoding API non-OK status", { status: data.status, lat, lng });
+      return { state: null, city: null, fromCache: false };
+    }
+
+    let rawState = null;
+    let city = null;
+
+    for (const result of (data.results || [])) {
+      for (const component of (result.address_components || [])) {
+        if (component.types.includes("administrative_area_level_1") && !rawState) {
+          rawState = component.long_name;
+        }
+        if (component.types.includes("locality") && !city) {
+          city = component.long_name;
+        }
+      }
+      if (rawState && city) break;
+    }
+
+    const state = normalizeStateName(rawState);
+
+    if (state) {
+      logger.info("State detected", { state, city, rawState });
+    } else if (rawState) {
+      logger.warn("State not recognized as Indian state", { rawState });
+    }
+
+    stateCache.set(key, { state, city, rawState, timestamp: Date.now() });
+    return { state, city, fromCache: false };
+  } catch (error) {
+    logger.error("State detection failed", { error: error.message, lat, lng });
+    return { state: null, city: null, fromCache: false };
+  }
+}
+
+export async function isUserInTargetStates(latitude, longitude, targetStates) {
+  if (!Array.isArray(targetStates) || targetStates.length === 0) return false;
+  const { state } = await detectStateFromCoordinates(latitude, longitude);
+  if (!state) return false;
+  const normalized = targetStates.map(normalizeStateName).filter(Boolean);
+  const match = normalized.includes(state);
+  logger.debug("State targeting", { state, targetStates: normalized, match });
+  return match;
+}
+
+export function clearStateCache() {
+  stateCache.clear();
+}
+
+export function getStateCacheStats() {
+  return { keys: stateCache.size };
+}