react-native-telpo 1.0.0

package/src/scanner/index.tsx

@@ -0,0 +1,397 @@
+/**
+ * TelpoScanner
+ *
+ * Provides:
+ *   1. `useTelpoScanner` hook  — for use inside React components
+ *   2. `TelpoScannerView`      — drop-in camera view component with built-in scanning
+ *
+ * Wraps react-native-vision-camera + vision-camera-code-scanner.
+ *
+ * Returns raw decoded value and format — you handle the business logic.
+ */
+
+import React, {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  forwardRef,
+} from 'react';
+import {
+  StyleSheet,
+  View,
+  Text,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+import {
+  TelpoErrorCode,
+  ScanResult,
+  ScannerOptions,
+  BarcodeFormat,
+} from '../types';
+import type { TelpoResult } from '../types';
+
+// ── Lazy-loaded peer deps ────────────────────────────────────────────────────
+
+type VisionCamera = any;
+type CodeScanner = any;
+
+let Camera: VisionCamera;
+let useCameraDevice: any;
+let useCodeScanner: CodeScanner;
+
+function loadScannerLib(): boolean {
+  try {
+    const vc = require('react-native-vision-camera');
+    Camera = vc.Camera;
+    useCameraDevice = vc.useCameraDevice;
+    useCodeScanner = vc.useCodeScanner;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function buildError(code: TelpoErrorCode, message: string): TelpoResult<never> {
+  return { success: false, error: { code, message } };
+}
+
+function wrapSuccess<T>(data: T): TelpoResult<T> {
+  return { success: true, data };
+}
+
+const FORMAT_MAP: Record<string, BarcodeFormat> = {
+  qr: 'QR_CODE',
+  'code-128': 'CODE_128',
+  'code-39': 'CODE_39',
+  'code-93': 'CODE_93',
+  'ean-13': 'EAN_13',
+  'ean-8': 'EAN_8',
+  'upc-a': 'UPC_A',
+  'upc-e': 'UPC_E',
+  aztec: 'AZTEC',
+  'data-matrix': 'DATA_MATRIX',
+  'pdf-417': 'PDF_417',
+  itf: 'ITF',
+};
+
+function mapFormat(vcFormat: string): BarcodeFormat {
+  return FORMAT_MAP[vcFormat.toLowerCase()] ?? 'QR_CODE';
+}
+
+const DEFAULT_FORMATS = [
+  'qr',
+  'code-128',
+  'code-39',
+  'ean-13',
+  'data-matrix',
+  'pdf-417',
+];
+
+// ── Hook ──────────────────────────────────────────────────────────────────────
+
+export interface UseTelpoScannerReturn {
+  /** Whether camera permission has been granted */
+  hasPermission: boolean;
+  /** Whether the library is loaded and camera is ready */
+  isReady: boolean;
+  /** Request camera permission */
+  requestPermission: () => Promise<boolean>;
+  /** The internal scan handler to pass to TelpoScannerView */
+  onScan: (codes: any[]) => void;
+  /** Last error, if any */
+  error: TelpoResult<never> | null;
+}
+
+/**
+ * React hook for managing scanner state and permissions.
+ *
+ * @example
+ * function MyScreen() {
+ *   const scanner = useTelpoScanner({
+ *     onResult: (result) => {
+ *       if (result.success) console.log(result.data.value);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <TelpoScannerView
+ *       scanner={scanner}
+ *       style={{ flex: 1 }}
+ *     />
+ *   );
+ * }
+ */
+export function useTelpoScanner(params: {
+  onResult: (result: TelpoResult<ScanResult>) => void;
+  options?: ScannerOptions;
+}): UseTelpoScannerReturn {
+  const { onResult, options = {} } = params;
+
+  const libLoaded = useRef(false);
+  const [isReady, setIsReady] = useState(false);
+  const [hasPermission, setHasPermission] = useState(false);
+  const [error, setError] = useState<TelpoResult<never> | null>(null);
+
+  // Dedupe tracking
+  const lastValue = useRef<string | null>(null);
+  const lastTime = useRef<number>(0);
+  const deduplicateMs = options.deduplicateMs ?? 2000;
+
+  useEffect(() => {
+    libLoaded.current = loadScannerLib();
+    if (!libLoaded.current) {
+      setError(
+        buildError(
+          TelpoErrorCode.SCANNER_NOT_ACTIVE,
+          'react-native-vision-camera is not installed. Run: npm install react-native-vision-camera'
+        )
+      );
+      return;
+    }
+    setIsReady(true);
+  }, []);
+
+  const requestPermission = useCallback(async (): Promise<boolean> => {
+    if (!libLoaded.current) return false;
+    try {
+      const status = await Camera.requestCameraPermission();
+      const granted = status === 'granted';
+      setHasPermission(granted);
+      if (!granted) {
+        setError(
+          buildError(TelpoErrorCode.SCANNER_CAMERA_PERMISSION_DENIED, 'Camera permission denied.')
+        );
+      }
+      return granted;
+    } catch {
+      setHasPermission(false);
+      return false;
+    }
+  }, []);
+
+  const onScan = useCallback(
+    (codes: any[]) => {
+      if (!codes || codes.length === 0) return;
+
+      const code = codes[0];
+      const value: string = code.value ?? code.displayValue ?? '';
+      if (!value) return;
+
+      const now = Date.now();
+
+      // Deduplicate: ignore same value within deduplicateMs window
+      if (value === lastValue.current && now - lastTime.current < deduplicateMs) {
+        return;
+      }
+
+      lastValue.current = value;
+      lastTime.current = now;
+
+      const format = mapFormat(code.type ?? 'qr');
+
+      onResult(
+        wrapSuccess<ScanResult>({
+          value,
+          format,
+          timestamp: now,
+        })
+      );
+    },
+    [onResult, deduplicateMs]
+  );
+
+  return {
+    hasPermission,
+    isReady,
+    requestPermission,
+    onScan,
+    error,
+  };
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+export interface TelpoScannerViewProps {
+  /** Scanner state from useTelpoScanner */
+  scanner: UseTelpoScannerReturn;
+  /** Style for the outer container */
+  style?: StyleProp<ViewStyle>;
+  /** Camera facing. Default: 'back' */
+  facing?: 'front' | 'back';
+  /** Barcode formats to scan. Default: QR + common 1D codes */
+  formats?: string[];
+  /** Whether scanning is active. Default: true */
+  active?: boolean;
+  /** Show a scan frame overlay. Default: true */
+  showOverlay?: boolean;
+  /** Overlay frame color. Default: '#00FF88' */
+  overlayColor?: string;
+  /** Placeholder shown when permission not yet granted */
+  permissionFallback?: React.ReactNode;
+}
+
+/**
+ * Drop-in camera view with built-in barcode/QR scanning.
+ *
+ * @example
+ * <TelpoScannerView
+ *   scanner={scanner}
+ *   style={{ flex: 1 }}
+ *   formats={['qr', 'code-128']}
+ * />
+ */
+export const TelpoScannerView = forwardRef<View, TelpoScannerViewProps>(
+  (
+    {
+      scanner,
+      style,
+      facing = 'back',
+      formats = DEFAULT_FORMATS,
+      active = true,
+      showOverlay = true,
+      overlayColor = '#00FF88',
+      permissionFallback,
+    },
+    ref
+  ) => {
+    const [permRequested, setPermRequested] = useState(false);
+
+    // Auto-request permission on mount
+    useEffect(() => {
+      if (!permRequested && scanner.isReady) {
+        setPermRequested(true);
+        scanner.requestPermission();
+      }
+    }, [scanner, permRequested]);
+
+    if (!scanner.isReady) {
+      return (
+        <View style={[styles.container, style]}>
+          <Text style={styles.errorText}>
+            {scanner.error?.success === false
+              ? scanner.error.error.message
+              : 'Loading camera...'}
+          </Text>
+        </View>
+      );
+    }
+
+    if (!scanner.hasPermission) {
+      if (permissionFallback) {
+        return <>{permissionFallback}</>;
+      }
+      return (
+        <View style={[styles.container, style]}>
+          <Text style={styles.errorText}>Camera permission required.</Text>
+          <Text style={styles.subText}>
+            Please grant camera access in device settings.
+          </Text>
+        </View>
+      );
+    }
+
+    return (
+      <InnerScannerView
+        ref={ref}
+        style={style}
+        facing={facing}
+        formats={formats}
+        active={active}
+        showOverlay={showOverlay}
+        overlayColor={overlayColor}
+        onScan={scanner.onScan}
+      />
+    );
+  }
+);
+
+TelpoScannerView.displayName = 'TelpoScannerView';
+
+// ── Inner view — only rendered when permission granted ────────────────────────
+
+interface InnerProps {
+  style?: StyleProp<ViewStyle>;
+  facing: 'front' | 'back';
+  formats: string[];
+  active: boolean;
+  showOverlay: boolean;
+  overlayColor: string;
+  onScan: (codes: any[]) => void;
+}
+
+const InnerScannerView = forwardRef<View, InnerProps>(
+  ({ style, facing, formats, active, showOverlay, overlayColor, onScan }, ref) => {
+    // These hooks are only called when lib is loaded (guarded by parent)
+    const device = useCameraDevice(facing);
+
+    const codeScanner = useCodeScanner({
+      codeTypes: formats,
+      onCodeScanned: onScan,
+    });
+
+    if (!device) {
+      return (
+        <View style={[styles.container, style]}>
+          <Text style={styles.errorText}>No camera device found.</Text>
+        </View>
+      );
+    }
+
+    return (
+      <View style={[styles.container, style]} ref={ref}>
+        <Camera
+          style={StyleSheet.absoluteFill}
+          device={device}
+          isActive={active}
+          codeScanner={codeScanner}
+        />
+        {showOverlay && (
+          <View style={styles.overlayContainer} pointerEvents="none">
+            <View style={[styles.scanFrame, { borderColor: overlayColor }]} />
+          </View>
+        )}
+      </View>
+    );
+  }
+);
+
+InnerScannerView.displayName = 'InnerScannerView';
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#000',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  errorText: {
+    color: '#fff',
+    fontSize: 16,
+    textAlign: 'center',
+    marginHorizontal: 24,
+  },
+  subText: {
+    color: '#aaa',
+    fontSize: 13,
+    textAlign: 'center',
+    marginTop: 8,
+    marginHorizontal: 24,
+  },
+  overlayContainer: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  scanFrame: {
+    width: 240,
+    height: 240,
+    borderWidth: 3,
+    borderRadius: 12,
+  },
+});
+
+export type { ScanResult, ScannerOptions, BarcodeFormat };

package/src/types/index.ts

@@ -0,0 +1,161 @@
+// ─────────────────────────────────────────────
+// Shared Types — react-native-telpo
+// ─────────────────────────────────────────────
+
+// ── Generic ──────────────────────────────────
+
+/** Standard SDK result wrapper */
+export type TelpoResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: TelpoError };
+
+export interface TelpoError {
+  code: TelpoErrorCode;
+  message: string;
+  raw?: unknown;
+}
+
+export enum TelpoErrorCode {
+  // Printer
+  PRINTER_NOT_CONNECTED = 'PRINTER_NOT_CONNECTED',
+  PRINTER_NO_PAPER = 'PRINTER_NO_PAPER',
+  PRINTER_BUSY = 'PRINTER_BUSY',
+  PRINTER_PERMISSION_DENIED = 'PRINTER_PERMISSION_DENIED',
+  PRINTER_INIT_FAILED = 'PRINTER_INIT_FAILED',
+  PRINTER_PRINT_FAILED = 'PRINTER_PRINT_FAILED',
+
+  // Scanner
+  SCANNER_CAMERA_PERMISSION_DENIED = 'SCANNER_CAMERA_PERMISSION_DENIED',
+  SCANNER_NOT_ACTIVE = 'SCANNER_NOT_ACTIVE',
+  SCANNER_ALREADY_ACTIVE = 'SCANNER_ALREADY_ACTIVE',
+
+  // NFC
+  NFC_NOT_SUPPORTED = 'NFC_NOT_SUPPORTED',
+  NFC_DISABLED = 'NFC_DISABLED',
+  NFC_PERMISSION_DENIED = 'NFC_PERMISSION_DENIED',
+  NFC_SCAN_CANCELLED = 'NFC_SCAN_CANCELLED',
+  NFC_READ_FAILED = 'NFC_READ_FAILED',
+  NFC_ALREADY_LISTENING = 'NFC_ALREADY_LISTENING',
+
+  // Generic
+  UNKNOWN = 'UNKNOWN',
+}
+
+// ── Printer Types ─────────────────────────────
+
+export interface PrinterDevice {
+  deviceName: string;
+  vendorId: string;
+  productId: string;
+}
+
+export type PrinterConnectionType = 'USB' | 'BLUETOOTH' | 'NETWORK';
+
+export interface PrinterOptions {
+  /** Connection type. Default: 'USB' (internal printer on M1/TPS320) */
+  connectionType?: PrinterConnectionType;
+  /** Required for BLUETOOTH connection */
+  bluetoothAddress?: string;
+  /** Required for NETWORK connection */
+  networkHost?: string;
+  /** Required for NETWORK connection. Default: 9100 */
+  networkPort?: number;
+}
+
+export type PrintAlignment = 'LEFT' | 'CENTER' | 'RIGHT';
+export type PrintFontSize = 'SMALL' | 'NORMAL' | 'LARGE' | 'DOUBLE';
+
+export interface PrintLine {
+  text: string;
+  alignment?: PrintAlignment;
+  bold?: boolean;
+  fontSize?: PrintFontSize;
+  underline?: boolean;
+}
+
+export interface PrintTicket {
+  /** Company / operator name shown at top */
+  operatorName?: string;
+  /** Route info, e.g. "Route 42 — City Centre → Airport" */
+  route?: string;
+  /** Passenger name or ID */
+  passenger?: string;
+  /** Ticket/transaction ID — also printed as barcode if provided */
+  ticketId: string;
+  /** Date/time string to print. Defaults to current datetime */
+  dateTime?: string;
+  /** Fare amount, e.g. "SLE 5.00" */
+  fare?: string;
+  /** Any extra key-value pairs to print */
+  extras?: Record<string, string>;
+  /** QR code value. If omitted, ticketId is used */
+  qrValue?: string;
+  /** Footer message */
+  footer?: string;
+}
+
+export interface PrintReceiptOptions {
+  /** Feed extra lines at end before cutter. Default: 4 */
+  feedLines?: number;
+  /** Cut the paper after printing. Default: true */
+  cutPaper?: boolean;
+}
+
+// ── Scanner Types ─────────────────────────────
+
+export type BarcodeFormat =
+  | 'QR_CODE'
+  | 'CODE_128'
+  | 'CODE_39'
+  | 'CODE_93'
+  | 'EAN_13'
+  | 'EAN_8'
+  | 'UPC_A'
+  | 'UPC_E'
+  | 'AZTEC'
+  | 'DATA_MATRIX'
+  | 'PDF_417'
+  | 'ITF';
+
+export interface ScanResult {
+  /** The raw decoded value from the barcode/QR */
+  value: string;
+  /** The format of the detected code */
+  format: BarcodeFormat;
+  /** Unix timestamp (ms) when the scan occurred */
+  timestamp: number;
+}
+
+export interface ScannerOptions {
+  /** Formats to detect. Default: all supported formats */
+  formats?: BarcodeFormat[];
+  /** Milliseconds to wait before allowing another scan on same value.
+   *  Prevents duplicate callbacks. Default: 2000ms */
+  deduplicateMs?: number;
+  /** Which camera to use. Default: 'back' */
+  camera?: 'back' | 'front';
+}
+
+// ── NFC Types ─────────────────────────────────
+
+export type NfcTechnology =
+  | 'NfcA'        // ISO 14443-3A
+  | 'NfcB'        // ISO 14443-3B
+  | 'IsoDep'      // ISO 14443-4
+  | 'MifareClassic'
+  | 'MifareUltralight'
+  | 'Ndef';
+
+export interface NfcTag {
+  /** Hex string of the tag UID, e.g. "04:AB:12:CD" */
+  uid: string;
+  /** Detected NFC technology */
+  technology: NfcTechnology;
+  /** Raw tag object from react-native-nfc-manager */
+  raw: Record<string, unknown>;
+}
+
+export interface NfcOptions {
+  /** Technologies to accept. Default: all */
+  technologies?: NfcTechnology[];
+}