@quantaroute/checkout 1.1.0 → 1.2.0

package/src/core/digipin.ts

@@ -0,0 +1,169 @@
+/**
+ * Official DigiPin Algorithm (Offline, Zero-dependency)
+ *
+ * Source: India Post – Department of Posts, Government of India
+ * Repository: https://github.com/INDIAPOST-gov/digipin
+ * License: Apache 2.0
+ *
+ * Developed in collaboration with:
+ *   – Indian Institute of Technology, Hyderabad
+ *   – National Remote Sensing Centre, ISRO
+ *
+ * This is a TypeScript port vendored for offline DigiPin processing
+ * without any external dependencies.
+ *
+ * DigiPin provides a geo-coded addressing system for India, dividing
+ * the country into ~4m × 4m grids with unique 10-character codes.
+ */
+
+/** DigiPin 4×4 grid character mapping */
+const DIGIPIN_GRID: string[][] = [
+  ['F', 'C', '9', '8'],
+  ['J', '3', '2', '7'],
+  ['K', '4', '5', '6'],
+  ['L', 'M', 'P', 'T'],
+];
+
+/** Geographic bounds for India */
+const BOUNDS = {
+  minLat: 2.5,
+  maxLat: 38.5,
+  minLon: 63.5,
+  maxLon: 99.5,
+};
+
+export interface DigiPinCoordinates {
+  latitude: string;
+  longitude: string;
+}
+
+/**
+ * Convert lat/lng coordinates to a DigiPin code.
+ * @throws if coordinates are outside India's bounds
+ */
+export function getDigiPin(lat: number, lon: number): string {
+  if (lat < BOUNDS.minLat || lat > BOUNDS.maxLat) {
+    throw new Error(
+      `Latitude ${lat} out of range. Must be between ${BOUNDS.minLat} and ${BOUNDS.maxLat}`
+    );
+  }
+  if (lon < BOUNDS.minLon || lon > BOUNDS.maxLon) {
+    throw new Error(
+      `Longitude ${lon} out of range. Must be between ${BOUNDS.minLon} and ${BOUNDS.maxLon}`
+    );
+  }
+
+  let minLat = BOUNDS.minLat;
+  let maxLat = BOUNDS.maxLat;
+  let minLon = BOUNDS.minLon;
+  let maxLon = BOUNDS.maxLon;
+
+  let digiPin = '';
+
+  for (let level = 1; level <= 10; level++) {
+    const latDiv = (maxLat - minLat) / 4;
+    const lonDiv = (maxLon - minLon) / 4;
+
+    let row = 3 - Math.floor((lat - minLat) / latDiv);
+    let col = Math.floor((lon - minLon) / lonDiv);
+
+    row = Math.max(0, Math.min(row, 3));
+    col = Math.max(0, Math.min(col, 3));
+
+    digiPin += DIGIPIN_GRID[row]![col]!;
+
+    if (level === 3 || level === 6) digiPin += '-';
+
+    maxLat = minLat + latDiv * (4 - row);
+    minLat = minLat + latDiv * (3 - row);
+    minLon = minLon + lonDiv * col;
+    maxLon = minLon + lonDiv;
+  }
+
+  return digiPin;
+}
+
+/**
+ * Decode a DigiPin code back to center-point coordinates.
+ * @throws if the DigiPin format is invalid
+ */
+export function getLatLngFromDigiPin(digiPin: string): DigiPinCoordinates {
+  const pin = digiPin.replace(/-/g, '');
+  if (pin.length !== 10) {
+    throw new Error('Invalid DIGIPIN: must be 10 characters (excluding dashes)');
+  }
+
+  let minLat = BOUNDS.minLat;
+  let maxLat = BOUNDS.maxLat;
+  let minLon = BOUNDS.minLon;
+  let maxLon = BOUNDS.maxLon;
+
+  for (let i = 0; i < 10; i++) {
+    const char = pin[i]!;
+    let found = false;
+    let ri = -1;
+    let ci = -1;
+
+    for (let r = 0; r < 4; r++) {
+      for (let c = 0; c < 4; c++) {
+        if (DIGIPIN_GRID[r]![c] === char) {
+          ri = r;
+          ci = c;
+          found = true;
+          break;
+        }
+      }
+      if (found) break;
+    }
+
+    if (!found) {
+      throw new Error(`Invalid character in DIGIPIN: '${char}'`);
+    }
+
+    const latDiv = (maxLat - minLat) / 4;
+    const lonDiv = (maxLon - minLon) / 4;
+
+    const lat1 = maxLat - latDiv * (ri + 1);
+    const lat2 = maxLat - latDiv * ri;
+    const lon1 = minLon + lonDiv * ci;
+    const lon2 = minLon + lonDiv * (ci + 1);
+
+    minLat = lat1;
+    maxLat = lat2;
+    minLon = lon1;
+    maxLon = lon2;
+  }
+
+  return {
+    latitude: ((minLat + maxLat) / 2).toFixed(6),
+    longitude: ((minLon + maxLon) / 2).toFixed(6),
+  };
+}
+
+/**
+ * Validate a DigiPin string (format + character check).
+ */
+export function isValidDigiPin(digiPin: string): boolean {
+  if (!digiPin || typeof digiPin !== 'string') return false;
+  if (!/^[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{4}$/i.test(digiPin.trim())) return false;
+  try {
+    getLatLngFromDigiPin(digiPin.trim().toUpperCase());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a lat/lng point is within India's DigiPin coverage area.
+ */
+export function isWithinIndia(lat: number, lon: number): boolean {
+  return (
+    lat >= BOUNDS.minLat &&
+    lat <= BOUNDS.maxLat &&
+    lon >= BOUNDS.minLon &&
+    lon <= BOUNDS.maxLon
+  );
+}
+
+export { BOUNDS as DIGIPIN_BOUNDS };

package/src/core/types.ts

@@ -0,0 +1,150 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyStyle = any; // CSSProperties on web · StyleProp<ViewStyle> on native
+
+// ─── Coordinates ────────────────────────────────────────────────────────────
+
+export interface Coordinates {
+  lat: number;
+  lng: number;
+}
+
+// ─── API Response Types ──────────────────────────────────────────────────────
+
+export interface AdministrativeInfo {
+  country?: string;
+  state: string;
+  division: string;
+  locality: string;
+  pincode: string;
+  delivery: string;
+  district: string;
+  mean_population_density?: number;
+  min_population_density?: number;
+  max_population_density?: number;
+}
+
+export interface LocationAlternative {
+  pincode: string;
+  name: string; // Locality name
+  branchType: string;
+  deliveryStatus: string;
+  district: string;
+  state: string;
+}
+
+export interface LocationLookupData {
+  coordinates: { latitude: number; longitude: number };
+  digipin: string;
+  administrative_info: AdministrativeInfo;
+  alternatives?: LocationAlternative[];
+  confidence: number;
+  source: string;
+}
+
+export interface LocationLookupResponse {
+  success: boolean;
+  data: LocationLookupData;
+  error?: string;
+  message?: string;
+}
+
+// ─── Complete Address (output) ───────────────────────────────────────────────
+
+export interface CompleteAddress {
+  /** Official India Post DigiPin code for this location (~4m x 4m precision) */
+  digipin: string;
+  /** Latitude of the confirmed pin location */
+  lat: number;
+  /** Longitude of the confirmed pin location */
+  lng: number;
+  /** Auto-filled: State */
+  state: string;
+  /** Auto-filled: District */
+  district: string;
+  /** Auto-filled: Postal division */
+  division: string;
+  /** Auto-filled: Locality / Post Office area */
+  locality: string;
+  /** Auto-filled: 6-digit pincode */
+  pincode: string;
+  /** Auto-filled: Delivery status ("Delivery" | "Non Delivery") */
+  delivery: string;
+  /** Auto-filled: Country */
+  country: string;
+  /** Manual: Flat / House number */
+  flatNumber: string;
+  /** Manual: Floor number */
+  floorNumber: string;
+  /** Manual: Building / Society name */
+  buildingName: string;
+  /** Manual: Street / Area */
+  streetName: string;
+  /** Combined formatted address string */
+  formattedAddress: string;
+}
+
+// ─── Component Props ─────────────────────────────────────────────────────────
+
+export interface MapPinSelectorProps {
+  onLocationConfirm: (lat: number, lng: number, digipin: string) => void;
+  defaultLat?: number;
+  defaultLng?: number;
+  /** Map height. String on web ('380px'), number on native (380). */
+  mapHeight?: string | number;
+  theme?: 'light' | 'dark';
+  /**
+   * URL to an India boundary GeoJSON file (FeatureCollection).
+   * When provided, a thin grey outline of India's border is drawn on the map
+   * to satisfy Indian government map policy requirements.
+   * The file is fetched in parallel with map initialisation — no visible delay.
+   * Example: indiaBoundaryUrl="/geojson/india.geojson"
+   */
+  indiaBoundaryUrl?: string;
+}
+
+export interface AddressFormProps {
+  digipin: string;
+  lat: number;
+  lng: number;
+  apiKey: string;
+  apiBaseUrl?: string;
+  onAddressComplete: (address: CompleteAddress) => void;
+  onBack: () => void;
+  onError?: (error: Error) => void;
+  theme?: 'light' | 'dark';
+}
+
+export interface CheckoutWidgetProps {
+  /**
+   * Your QuantaRoute API key.
+   * Get one free at https://quantaroute.com
+   */
+  apiKey: string;
+  /** API base URL. Defaults to https://api.quantaroute.com */
+  apiBaseUrl?: string;
+  /** Callback fired when user completes the full address entry. */
+  onComplete: (address: CompleteAddress) => void;
+  /** Optional error handler. */
+  onError?: (error: Error) => void;
+  /** Default map latitude (center). If provided, map opens at this location. */
+  defaultLat?: number;
+  /** Default map longitude (center). */
+  defaultLng?: number;
+  /** Color theme. Defaults to 'light'. */
+  theme?: 'light' | 'dark';
+  /** CSS class name(s) to add to the root element (web only). */
+  className?: string;
+  /** Inline styles for the root element (CSSProperties on web, StyleProp<ViewStyle> on native). */
+  style?: AnyStyle;
+  /** Map area height. String on web ('380px'), number on native (380). Defaults to '380px' / 380. */
+  mapHeight?: string | number;
+  /** Widget header title. Defaults to 'Add Delivery Address'. */
+  title?: string;
+  /**
+   * URL to an India boundary GeoJSON file (FeatureCollection).
+   * When provided, a thin grey outline is drawn on the map for legal compliance.
+   * Host the file in your app's public folder and pass its path here.
+   * Example: indiaBoundaryUrl="/geojson/india.geojson"
+   */
+  indiaBoundaryUrl?: string;
+}

package/src/hooks/useDigiPin.ts

@@ -0,0 +1,20 @@
+import { useMemo } from 'react';
+import { getDigiPin, isWithinIndia } from '../core/digipin';
+
+/**
+ * Compute a DigiPin code from lat/lng entirely offline (no API call).
+ * Returns null if coordinates are outside India's bounds.
+ *
+ * The calculation is pure math (~0.1ms), so no debouncing is needed
+ * even when called on every marker drag event.
+ */
+export function useDigiPin(lat: number, lng: number): string | null {
+  return useMemo(() => {
+    if (!isWithinIndia(lat, lng)) return null;
+    try {
+      return getDigiPin(lat, lng);
+    } catch {
+      return null;
+    }
+  }, [lat, lng]);
+}

package/src/hooks/useGeolocation.native.ts

@@ -0,0 +1,55 @@
+import { useState, useCallback } from 'react';
+import * as Location from 'expo-location';
+
+interface GeoState {
+  loading: boolean;
+  error: string | null;
+}
+
+/**
+ * Native (iOS/Android) geolocation hook using expo-location.
+ * Identical public API to useGeolocation.ts (web version) —
+ * Metro resolves this file on native, the .ts file on web.
+ */
+export function useGeolocation() {
+  const [state, setState] = useState<GeoState>({ loading: false, error: null });
+
+  const locate = useCallback((onSuccess: (lat: number, lng: number) => void) => {
+    setState({ loading: true, error: null });
+
+    void (async () => {
+      try {
+        const { status } = await Location.requestForegroundPermissionsAsync();
+
+        if (status !== Location.PermissionStatus.GRANTED) {
+          setState({
+            loading: false,
+            error: 'Location permission denied. Please enable it in Settings.',
+          });
+          return;
+        }
+
+        const loc = await Location.getCurrentPositionAsync({
+          accuracy: Location.Accuracy.High,
+        });
+
+        setState({ loading: false, error: null });
+        onSuccess(loc.coords.latitude, loc.coords.longitude);
+      } catch (err) {
+        let message = 'Unable to get location. Try again or place the pin manually.';
+        if (err instanceof Error) {
+          if (err.message.includes('timed out')) {
+            message = 'Location request timed out. Try again.';
+          }
+        }
+        setState({ loading: false, error: message });
+      }
+    })();
+  }, []);
+
+  const clearError = useCallback(() => {
+    setState((s) => ({ ...s, error: null }));
+  }, []);
+
+  return { ...state, locate, clearError };
+}

package/src/hooks/useGeolocation.ts

@@ -0,0 +1,48 @@
+import { useState, useCallback } from 'react';
+
+interface GeoState {
+  loading: boolean;
+  error: string | null;
+}
+
+/**
+ * Hook to imperatively request the user's current GPS position.
+ * Returns a `locate(onSuccess)` callback to trigger the permission prompt.
+ */
+export function useGeolocation() {
+  const [state, setState] = useState<GeoState>({ loading: false, error: null });
+
+  const locate = useCallback((onSuccess: (lat: number, lng: number) => void) => {
+    if (!navigator.geolocation) {
+      setState({ loading: false, error: 'Geolocation is not supported by your browser.' });
+      return;
+    }
+
+    setState({ loading: true, error: null });
+
+    navigator.geolocation.getCurrentPosition(
+      ({ coords }) => {
+        setState({ loading: false, error: null });
+        onSuccess(coords.latitude, coords.longitude);
+      },
+      (err) => {
+        let message = 'Unable to get location.';
+        if (err.code === err.PERMISSION_DENIED) {
+          message = 'Location permission denied. Please enable it in browser settings.';
+        } else if (err.code === err.POSITION_UNAVAILABLE) {
+          message = 'Location unavailable. Try again or place the pin manually.';
+        } else if (err.code === err.TIMEOUT) {
+          message = 'Location request timed out. Try again.';
+        }
+        setState({ loading: false, error: message });
+      },
+      { enableHighAccuracy: true, timeout: 12_000, maximumAge: 0 }
+    );
+  }, []);
+
+  const clearError = useCallback(() => {
+    setState((s) => ({ ...s, error: null }));
+  }, []);
+
+  return { ...state, locate, clearError };
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * @quantaroute/checkout
+ *
+ * DigiPin-powered smart address checkout widget — one import, three platforms.
+ *
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │  Platform        │  Resolved by                │  Map engine    │
+ * │──────────────────│────────────────────────────────────────────── │
+ * │  Web             │  Vite / Webpack / Next.js   │  MapLibre GL JS│
+ * │  iOS / Android   │  Metro (Expo / React Native)│  expo-osm-sdk  │
+ * └─────────────────────────────────────────────────────────────────┘
+ *
+ * Web usage:
+ *   import { CheckoutWidget } from '@quantaroute/checkout';
+ *   import '@quantaroute/checkout/style.css';
+ *
+ * Native usage (Expo / React Native):
+ *   import { CheckoutWidget } from '@quantaroute/checkout';
+ *   // No CSS import needed — styles are React Native StyleSheet objects
+ *
+ * @see https://quantaroute.com/docs/checkout
+ */
+
+// ── Main component (default export as well) ───────────────────────────────────
+export { default as CheckoutWidget } from './components/CheckoutWidget';
+export { default } from './components/CheckoutWidget';
+
+// ── Sub-components (for advanced composition) ─────────────────────────────────
+export { default as MapPinSelector } from './components/MapPinSelector';
+export { default as AddressForm } from './components/AddressForm';
+
+// ── Core utilities (offline, zero-dependency) ─────────────────────────────────
+export {
+  getDigiPin,
+  getLatLngFromDigiPin,
+  isValidDigiPin,
+  isWithinIndia,
+  DIGIPIN_BOUNDS,
+} from './core/digipin';
+
+// ── API client ────────────────────────────────────────────────────────────────
+export { lookupLocation, reverseGeocode } from './core/api';
+export type { AddressComponents, ReverseGeocodeResponse } from './core/api';
+
+// ── Hooks ─────────────────────────────────────────────────────────────────────
+export { useGeolocation } from './hooks/useGeolocation';
+export { useDigiPin } from './hooks/useDigiPin';
+
+// ── TypeScript types ──────────────────────────────────────────────────────────
+export type {
+  CheckoutWidgetProps,
+  MapPinSelectorProps,
+  AddressFormProps,
+  CompleteAddress,
+  AdministrativeInfo,
+  LocationAlternative,
+  LocationLookupResponse,
+  Coordinates,
+} from './core/types';