@quantaroute/checkout 1.0.0

package/README.md

@@ -0,0 +1,389 @@
+# @quantaroute/checkout
+
+> **DigiPin-powered smart address checkout widget for Indian e-commerce.**
+> Two-step: Map pin → Auto-filled form. Works in any React/Next.js/Nuxt/Vite app.
+
+[![Made in India](https://img.shields.io/badge/Made%20in-India%20🇮🇳-orange)](https://quantaroute.com)
+[![DigiPin](https://img.shields.io/badge/DigiPin-India%20Post-blue)](https://www.indiapost.gov.in)
+[![Map](https://img.shields.io/badge/Map-Carto%20Positron%20(free)-green)](https://carto.com)
+[![License](https://img.shields.io/badge/License-MIT-lightgrey)](./LICENSE)
+
+---
+
+## What it does
+
+Replaces your broken Indian address form with a two-step Uber-style flow:
+
+```
+Step 1 – Map Pin                    Step 2 – Auto-fill + Details
+┌──────────────────────────┐        ┌──────────────────────────┐
+│  [DigiPin: 39J-438-TJC7] │        │  📍 Auto-detected         │
+│                           │        │  State:    Delhi          │
+│    🗺 Carto Positron map  │  ──►  │  District: New Delhi     │
+│         📍 ← drag         │        │  Pincode:  110011         │
+│                           │        │  ✓ Deliverable            │
+│  [📡 Locate Me]           │        │  🏠 Add details           │
+│  [Confirm Location →]     │        │  Flat No:  [_________]    │
+└──────────────────────────┘        │  [← Adjust] [Save ✓]    │
+                                     └──────────────────────────┘
+```
+
+**Key features:**
+
+- DigiPin shown **offline** in real-time as the user drags the pin (~4m×4m precision)
+- **No Google Maps.** Free Carto Positron vector basemap (MapLibre GL JS)
+- Auto-fills State, District, Locality, Pincode, Delivery status from QuantaRoute API
+- Manual fields: Flat no., Floor, Building (OSM-pre-filled), Street/Area (OSM-pre-filled)
+- Mobile-first (full-screen on phones, card on desktop)
+- Dark mode, reduced-motion, keyboard navigation, ARIA labels
+- TypeScript, zero runtime deps beyond MapLibre + React
+
+---
+
+## Quick start
+
+### 0 · Get an API key
+
+1. Sign up at **[developers.quantaroute.com](https://developers.quantaroute.com)**
+2. Create a project → copy your **API key**
+3. Store it as an environment variable in your app:
+
+| Framework | Variable name convention |
+|-----------|--------------------------|
+| Next.js | `NEXT_PUBLIC_QUANTAROUTE_KEY` in `.env.local` |
+| Vite | `VITE_QR_API_KEY` in `.env` |
+| Nuxt | `NUXT_PUBLIC_QR_API_KEY` in `.env` |
+| Node/Express backend | `QUANTAROUTE_KEY` (server-side only) |
+
+> **Never hard-code or commit API keys to git.**
+
+---
+
+### 1 · Install
+
+```bash
+npm install @quantaroute/checkout maplibre-gl
+# or
+yarn add @quantaroute/checkout maplibre-gl
+```
+
+### 2 · Import CSS
+
+```ts
+// In your app's entry file (main.tsx / _app.tsx / nuxt.config.ts, etc.)
+import 'maplibre-gl/dist/maplibre-gl.css';
+import '@quantaroute/checkout/dist/style.css';
+```
+
+### 3 · Drop it in
+
+```tsx
+import { CheckoutWidget } from '@quantaroute/checkout';
+
+export default function CheckoutPage() {
+  return (
+    <CheckoutWidget
+      apiKey={process.env.NEXT_PUBLIC_QUANTAROUTE_KEY!}  {/* never hard-code keys */}
+      onComplete={(address) => {
+        console.log(address.digipin);          // "39J-438-TJC7"
+        console.log(address.pincode);          // "110011"
+        console.log(address.formattedAddress); // "Flat 4B, Floor 3rd, ..."
+        // → send to your backend / payment gateway
+      }}
+    />
+  );
+}
+```
+
+> **Get your API key** (free tier: 25,000 requests/month) →
+> **[developers.quantaroute.com](https://developers.quantaroute.com)**
+>
+> Store it as an environment variable — **never commit API keys to source control**.
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | **required** | QuantaRoute API key |
+| `onComplete` | `(addr: CompleteAddress) => void` | **required** | Fired after user saves address |
+| `apiBaseUrl` | `string` | `https://api.quantaroute.com` | Custom API URL (self-hosted) |
+| `onError` | `(err: Error) => void` | – | Optional error handler |
+| `defaultLat` | `number` | India center | Pre-center the map here |
+| `defaultLng` | `number` | India center | Pre-center the map here |
+| `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
+| `mapHeight` | `string` | `'380px'` | CSS height of the map area |
+| `title` | `string` | `'Add Delivery Address'` | Widget header text |
+| `className` | `string` | – | Extra class on root element |
+| `style` | `CSSProperties` | – | Inline styles on root element |
+
+---
+
+## `CompleteAddress` output
+
+```ts
+interface CompleteAddress {
+  digipin: string;          // "39J-438-TJC7"
+  lat: number;              // 28.61390
+  lng: number;              // 77.20900
+
+  // Auto-filled from QuantaRoute API
+  state: string;            // "Delhi"
+  district: string;         // "New Delhi"
+  division: string;         // "New Delhi Central"
+  locality: string;         // "Nirman Bhawan SO"
+  pincode: string;          // "110011"
+  delivery: string;         // "Delivery" | "Non Delivery"
+  country: string;          // "India"
+
+  // Manual entry by user
+  flatNumber: string;       // "4B"
+  floorNumber: string;      // "3rd"
+  buildingName: string;     // "Sunshine Apartments" (pre-filled from Nominatim OSM)
+  streetName: string;       // "MG Road, Action Area I" (pre-filled from road + suburb)
+
+  formattedAddress: string; // "4B, 3rd Floor, Sunshine Apartments, MG Road, ..."
+}
+```
+
+---
+
+## Framework integration guides
+
+### Next.js (App Router)
+
+```tsx
+// app/checkout/page.tsx
+'use client';                         // ← required (MapLibre is browser-only)
+
+import dynamic from 'next/dynamic';
+
+const CheckoutWidget = dynamic(
+  () => import('@quantaroute/checkout').then((m) => m.CheckoutWidget),
+  { ssr: false }                      // ← required (no SSR for map)
+);
+
+export default function CheckoutPage() {
+  return (
+    <main className="max-w-lg mx-auto p-4">
+      <CheckoutWidget
+        apiKey={process.env.NEXT_PUBLIC_QUANTAROUTE_KEY!}   {/* set in .env.local */}
+        onComplete={(addr) => console.log(addr)}
+      />
+    </main>
+  );
+}
+```
+
+Add CSS imports to `app/layout.tsx`:
+```tsx
+import 'maplibre-gl/dist/maplibre-gl.css';
+import '@quantaroute/checkout/dist/style.css';
+```
+
+---
+
+### Next.js (Pages Router)
+
+```tsx
+// pages/checkout.tsx
+import dynamic from 'next/dynamic';
+const CheckoutWidget = dynamic(() => import('@quantaroute/checkout'), { ssr: false });
+
+export default function CheckoutPage() {
+  return (
+    <CheckoutWidget
+      apiKey={process.env.NEXT_PUBLIC_QUANTAROUTE_KEY!}  {/* .env.local */}
+      onComplete={(a) => console.log(a)}
+    />
+  );
+}
+```
+
+---
+
+### Nuxt 3
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  css: [
+    'maplibre-gl/dist/maplibre-gl.css',
+    '@quantaroute/checkout/dist/style.css',
+  ],
+});
+```
+
+```vue
+<!-- components/AddressWidget.client.vue -->
+<!-- The .client suffix ensures this only renders on the client -->
+<script setup lang="ts">
+import { CheckoutWidget } from '@quantaroute/checkout';
+
+function handleComplete(address) {
+  console.log(address.digipin, address.formattedAddress);
+}
+</script>
+
+<template>
+  <!-- API key via runtimeConfig → useRuntimeConfig().public.qrApiKey -->
+  <CheckoutWidget
+    :api-key="runtimeConfig.public.qrApiKey"
+    map-height="360px"
+    @complete="handleComplete"
+  />
+</template>
+```
+
+---
+
+### Vite + React
+
+```tsx
+// src/App.tsx
+import 'maplibre-gl/dist/maplibre-gl.css';
+import '@quantaroute/checkout/dist/style.css';
+import { CheckoutWidget } from '@quantaroute/checkout';
+
+function App() {
+  return (
+    <div style={{ padding: '20px' }}>
+      <CheckoutWidget
+        apiKey={import.meta.env.VITE_QR_API_KEY}
+        onComplete={(addr) => console.log('Saved:', addr)}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### Vanilla JS (UMD / Script tag)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css" />
+  <link rel="stylesheet" href="https://unpkg.com/@quantaroute/checkout/dist/style.css" />
+</head>
+<body>
+  <div id="checkout-root"></div>
+
+  <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+  <script src="https://unpkg.com/@quantaroute/checkout/dist/lib/quantaroute-checkout.umd.js"></script>
+  <script>
+    const { createRoot } = ReactDOM;
+    const { CheckoutWidget } = QuantaRouteCheckout;
+
+    // Replace window.__QR_API_KEY__ with your key from developers.quantaroute.com
+    // In production, inject this via server-side template or env variable.
+    createRoot(document.getElementById('checkout-root')).render(
+      React.createElement(CheckoutWidget, {
+        apiKey: window.__QR_API_KEY__ || '',
+        onComplete: (addr) => console.log('Done:', addr),
+      })
+    );
+  </script>
+</body>
+</html>
+```
+
+---
+
+### React Native (coming soon)
+
+A React Native version is planned that will use `react-native-maps` + the same offline DigiPin algorithm and QuantaRoute API. Track progress in issues.
+
+---
+
+## Advanced usage
+
+### Use sub-components individually
+
+```tsx
+import { MapPinSelector, AddressForm, getDigiPin, isWithinIndia } from '@quantaroute/checkout';
+
+// Offline DigiPin (no API call needed)
+const dp = getDigiPin(28.6139, 77.2090); // "39J-438-TJC7"
+const valid = isWithinIndia(28.6139, 77.2090); // true
+
+// Custom two-step flow
+function MyCheckout() {
+  const [loc, setLoc] = useState(null);
+
+  return loc == null
+    ? <MapPinSelector onLocationConfirm={(lat, lng, dp) => setLoc({ lat, lng, dp })} />
+    : <AddressForm {...loc} digipin={loc.dp} apiKey="..." onAddressComplete={...} onBack={...} />;
+}
+```
+
+### Custom theme with CSS variables
+
+```css
+/* Override the design tokens in your global CSS */
+.qr-checkout {
+  --qr-primary:      #6366f1;   /* indigo */
+  --qr-primary-dark: #4f46e5;
+  --qr-radius:       8px;
+  --qr-font:         'Poppins', sans-serif;
+}
+```
+
+---
+
+## Map tile license
+
+This widget uses **Carto Positron** vector tiles via MapLibre GL JS.
+
+- Free for commercial use (attribution required)
+- Attribution: `© OpenStreetMap contributors © CARTO`
+- Does **not** use Google Maps, Mapbox, or OSM raster tiles
+- No API key required for Carto basemaps
+
+---
+
+## DigiPin license
+
+The offline DigiPin algorithm is the official India Post implementation:
+
+- **Source:** [github.com/INDIAPOST-gov/digipin](https://github.com/INDIAPOST-gov/digipin)
+- **Developed by:** India Post, IIT Hyderabad, ISRO NRSC
+- **License:** Apache 2.0
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/quantaroute/checkout.git
+cd quantaroute-checkout
+
+npm install
+npm run dev        # Dev server at http://localhost:5173
+
+npm run type-check # TypeScript check
+npm run build      # Build demo
+npm run build:lib  # Build library (dist/lib/)
+```
+
+---
+
+## Changelog
+
+### v1.0.0
+
+- Initial release
+- MapLibre GL + Carto Positron (free, no API key)
+- Offline DigiPin generation (real-time on pin drag)
+- QuantaRoute location lookup API integration
+- Mobile-first responsive design
+- Dark mode, reduced-motion, keyboard accessible
+- React / Next.js / Nuxt / Vite / Vanilla JS support
+
+---
+
+**Made with ❤️ in India · Powered by [QuantaRoute](https://quantaroute.com)**

package/dist/lib/index.d.ts

@@ -0,0 +1,257 @@
+import { CSSProperties } from 'react';
+import { default as default_2 } from 'react';
+
+/**
+ * Address components from Nominatim/OpenStreetMap (via reverse geocoding).
+ */
+export declare interface AddressComponents {
+    house_number?: string;
+    road?: string;
+    neighbourhood?: string;
+    suburb?: string;
+    city?: string;
+    state?: string;
+    postcode?: string;
+    country?: string;
+    country_code?: string;
+    name?: string;
+    addr_housename?: string;
+    addr_place?: string;
+    building?: string;
+    building_name?: string;
+    [key: string]: string | undefined;
+}
+
+export declare const AddressForm: default_2.FC<AddressFormProps>;
+
+export declare 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 declare 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;
+}
+
+/**
+ * QuantaRoute Checkout Widget
+ *
+ * A two-step, mobile-first address collection component:
+ *   Step 1 – Map: user pins their exact location (DigiPin shown offline, real-time)
+ *   Step 2 – Form: auto-filled address + manual flat/building details
+ *
+ * Works in React, Next.js, Nuxt (via nuxt-module), Vite, etc.
+ * Embed as a script tag (vanilla JS) via the UMD build.
+ */
+declare const CheckoutWidget: default_2.FC<CheckoutWidgetProps>;
+export { CheckoutWidget }
+export default CheckoutWidget;
+
+export declare 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. */
+    className?: string;
+    /** Inline styles for the root element. */
+    style?: CSSProperties;
+    /** Map area height. Defaults to '380px'. */
+    mapHeight?: string;
+    /** Widget header title. Defaults to 'Add Delivery Address'. */
+    title?: string;
+}
+
+export declare 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;
+}
+
+export declare interface Coordinates {
+    lat: number;
+    lng: number;
+}
+
+/** Geographic bounds for India */
+export declare const DIGIPIN_BOUNDS: {
+    minLat: number;
+    maxLat: number;
+    minLon: number;
+    maxLon: number;
+};
+
+declare interface DigiPinCoordinates {
+    latitude: string;
+    longitude: string;
+}
+
+/**
+ * Convert lat/lng coordinates to a DigiPin code.
+ * @throws if coordinates are outside India's bounds
+ */
+export declare function getDigiPin(lat: number, lon: number): string;
+
+/**
+ * Decode a DigiPin code back to center-point coordinates.
+ * @throws if the DigiPin format is invalid
+ */
+export declare function getLatLngFromDigiPin(digiPin: string): DigiPinCoordinates;
+
+/**
+ * Validate a DigiPin string (format + character check).
+ */
+export declare function isValidDigiPin(digiPin: string): boolean;
+
+/**
+ * Check if a lat/lng point is within India's DigiPin coverage area.
+ */
+export declare function isWithinIndia(lat: number, lon: number): boolean;
+
+export declare interface LocationAlternative {
+    pincode: string;
+    name: string;
+    branchType: string;
+    deliveryStatus: string;
+    district: string;
+    state: string;
+}
+
+declare interface LocationLookupData {
+    coordinates: {
+        latitude: number;
+        longitude: number;
+    };
+    digipin: string;
+    administrative_info: AdministrativeInfo;
+    alternatives?: LocationAlternative[];
+    confidence: number;
+    source: string;
+}
+
+export declare interface LocationLookupResponse {
+    success: boolean;
+    data: LocationLookupData;
+    error?: string;
+    message?: string;
+}
+
+/**
+ * Call QuantaRoute's Location Lookup API.
+ * Converts lat/lng → full Indian administrative address + DigiPin.
+ */
+export declare function lookupLocation(lat: number, lng: number, apiKey: string, baseUrl?: string): Promise<LocationLookupResponse>;
+
+export declare const MapPinSelector: default_2.FC<MapPinSelectorProps>;
+
+export declare interface MapPinSelectorProps {
+    onLocationConfirm: (lat: number, lng: number, digipin: string) => void;
+    defaultLat?: number;
+    defaultLng?: number;
+    mapHeight?: string;
+    theme?: 'light' | 'dark';
+}
+
+/**
+ * Call QuantaRoute's Reverse Geocoding API.
+ * Converts DigiPin → address components from Nominatim/OpenStreetMap.
+ */
+export declare function reverseGeocode(digipin: string, apiKey: string, baseUrl?: string): Promise<ReverseGeocodeResponse>;
+
+/**
+ * Response from /v1/digipin/reverse endpoint.
+ */
+export declare interface ReverseGeocodeResponse {
+    success: boolean;
+    data: {
+        digipin: string;
+        address: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+        confidence: number;
+        displayName: string;
+        addressComponents: AddressComponents;
+    };
+    error?: string;
+    message?: string;
+}
+
+/**
+ * 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 declare function useDigiPin(lat: number, lng: number): string | null;
+
+/**
+ * Hook to imperatively request the user's current GPS position.
+ * Returns a `locate(onSuccess)` callback to trigger the permission prompt.
+ */
+export declare function useGeolocation(): {
+    locate: (onSuccess: (lat: number, lng: number) => void) => void;
+    clearError: () => void;
+    loading: boolean;
+    error: string | null;
+};
+
+export { }