SnapKYC SDK

A React TypeScript SDK for QR code verification components with SnapKYC integration.

Installation

npm install snapkyc-sdk
# or
yarn add snapkyc-sdk

Quick Start

Basic Usage

import React from 'react';
import { QRCodeDisplay, QRCodePortal, configureSnapKYC } from 'snapkyc-sdk';

// Configure the SDK (optional - uses default API endpoint if not configured)
configureSnapKYC({
  apiBaseUrl: 'https://your-api-endpoint.com',
  defaultQRSize: 300,
  pollingInterval: 3000,
});

// Simple QR Code Display
function App() {
  const handleVerificationChange = (status: string) => {
    console.log('Verification status:', status);
  };

  return (
    <div>
      <QRCodeDisplay
        data="https://your-verification-url.com"
        size={300}
        autoGenerate={true}
        onVerificationStatusChange={handleVerificationChange}
      />
    </div>
  );
}

Complete Portal Example

import React from 'react';
import { QRCodePortal, CheckInData } from 'snapkyc-sdk';

function CheckInApp() {
  const checkInData: CheckInData = {
    guestName: "John Doe",
    roomNumber: "101",
    checkInDate: "2024-01-15",
    phoneNumber: "+1234567890"
  };

  const handleVerificationComplete = (data) => {
    console.log('Verification completed:', data);
    // Handle successful verification
  };

  const handleNewCheckIn = () => {
    console.log('Starting new check-in process');
  };

  return (
    <QRCodePortal
      checkInData={checkInData}
      onVerificationComplete={handleVerificationComplete}
      onNewCheckIn={handleNewCheckIn}
      showAppDownloadLinks={true}
      customStyling={{
        primaryColor: '#2563eb',
        borderRadius: '0.75rem'
      }}
    />
  );
}

Components

QRCodeDisplay

The core QR code generation and verification component.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | string | - | Required. The data to encode in the QR code | | size | number | 300 | Size of the QR code in pixels | | autoGenerate | boolean | false | Whether to generate QR code automatically | | onVerificationStatusChange | (status: string) => void | - | Callback when verification status changes | | apiBaseUrl | string | - | Override the default API base URL |

Example

<QRCodeDisplay
  data="https://verification-url.com"
  size={260}
  autoGenerate={true}
  onVerificationStatusChange={(status) => {
    if (status === 'success') {
      // Handle successful verification
    }
  }}
/>

QRCodePortal

A complete portal interface for QR code verification with app download links and customization options.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | checkInData | CheckInData | - | Required. Guest check-in information | | onNewCheckIn | () => void | - | Callback when user wants to start a new check-in | | onVerificationComplete | (data: VerificationStatus) => void | - | Callback when verification is completed | | apiBaseUrl | string | - | Override the default API base URL | | customQRDataGenerator | (data: CheckInData) => string | - | Custom function to generate QR data | | showAppDownloadLinks | boolean | true | Whether to show app download buttons | | customStyling | object | {} | Custom styling options |

CheckInData Type

interface CheckInData {
  guestName: string;
  roomNumber: string;
  checkInDate: string;
  phoneNumber: string;
}

Custom Styling Options

interface CustomStyling {
  primaryColor?: string;      // Primary button and accent color
  secondaryColor?: string;    // Secondary elements color
  borderRadius?: string;      // Border radius for components
}

Hooks

useQRGeneration

Hook for managing QR code generation state.

import { useQRGeneration } from 'snapkyc-sdk';

function MyComponent() {
  const {
    qrImageUrl,
    loading,
    error,
    txnId,
    qrGenerated,
    generateQR,
    reset,
  } = useQRGeneration(
    'https://my-verification-url.com',
    300,
    true // autoGenerate
  );

  return (
    <div>
      {loading && <p>Generating QR code...</p>}
      {error && <p>Error: {error}</p>}
      {qrImageUrl && <img src={qrImageUrl} alt="QR Code" />}
      <button onClick={generateQR}>Generate New QR</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

useVerificationPolling

Hook for polling verification status.

import { useVerificationPolling } from 'snapkyc-sdk';

function MyComponent() {
  const verificationStatus = useVerificationPolling(
    'transaction-id',
    true, // isActive
    (status) => console.log('Status changed:', status)
  );

  return (
    <div>
      <p>Status: {verificationStatus.status}</p>
      {verificationStatus.message && (
        <p>Message: {verificationStatus.message}</p>
      )}
    </div>
  );
}

useResponsiveQRSize

Hook for responsive QR code sizing.

import { useResponsiveQRSize } from 'snapkyc-sdk';

function MyComponent() {
  const responsiveSize = useResponsiveQRSize(300);

  return (
    <div>
      <p>QR Size: {responsiveSize}px</p>
    </div>
  );
}

Configuration

Global Configuration

Configure the SDK globally at the start of your application:

import { configureSnapKYC } from 'snapkyc-sdk';

configureSnapKYC({
  apiBaseUrl: 'https://your-api-endpoint.com',
  defaultQRSize: 300,
  pollingInterval: 3000,
  customHeaders: {
    'Authorization': 'Bearer your-token',
    'X-Custom-Header': 'value'
  }
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiBaseUrl | string | 'https://api.snapkyc.com' | Base URL for API calls | | defaultQRSize | number | 300 | Default QR code size | | pollingInterval | number | 3000 | Status polling interval in ms | | customHeaders | object | { 'ngrok-skip-browser-warning': 'true' } | Custom HTTP headers |

Utility Functions

generateQRCode

Manually generate a QR code:

import { generateQRCode } from 'snapkyc-sdk';

const result = await generateQRCode(
  'https://verification-url.com',
  300
);

console.log('QR Image URL:', result.qrImageUrl);
console.log('Transaction ID:', result.transactionId);

pollVerificationStatus

Manually poll verification status:

import { pollVerificationStatus } from 'snapkyc-sdk';

const status = await pollVerificationStatus('transaction-id');
console.log('Status:', status);

generateDefaultQRData

Generate default QR data format:

import { generateDefaultQRData } from 'snapkyc-sdk';

const qrData = generateDefaultQRData(
  'John Doe',
  '101',
  '2024-01-15',
  'https://your-hotel.com'
);

Styling

The SDK uses Tailwind CSS classes for styling. Make sure your project has Tailwind CSS configured, or the components will use default browser styles.

Custom CSS

If you're not using Tailwind CSS, you can override the component styles:

/* Override QR code container */
.snapkyc-qr-container {
  /* Your custom styles */
}

/* Override status indicators */
.snapkyc-status-success {
  /* Your custom styles */
}

.snapkyc-status-pending {
  /* Your custom styles */
}

.snapkyc-status-failed {
  /* Your custom styles */
}

TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions. All components, hooks, and utilities are fully typed.

import type {
  QRCodeDisplayProps,
  QRCodePortalProps,
  VerificationStatus,
  CheckInData,
  SnapKYCConfig
} from 'snapkyc-sdk';

Error Handling

The SDK includes built-in error handling for common scenarios:

• Network connectivity issues
• Invalid API responses
• QR code generation failures
• Verification polling errors

Handle errors in your application:

<QRCodeDisplay
  data="invalid-data"
  onVerificationStatusChange={(status) => {
    if (status === 'failed') {
      // Handle verification failure
      console.log('Verification failed');
    }
  }}
/>

Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, email [email protected] or create an issue on our GitHub repository.

Changelog

v1.0.0

• Initial release
• QRCodeDisplay component
• QRCodePortal component
• React hooks for QR generation and verification polling
• TypeScript support
• Comprehensive documentation