SafePassage SDK Tester & Demo Site

A dual-purpose application that serves as both an internal SDK testing tool and an external-facing demo site for potential customers.

Purpose

This application provides two distinct modes:

1. Demo Site (demo.safepassageapp.com)

• Customer-facing demonstration of SafePassage verification
• Two verification options: Age Verification and Identity Verification
• No sign-up required for potential customers to try
• Conversion-focused design with clear CTAs
• Analytics tracking for demo conversions

2. SDK Testing Tool (localhost:3456/test)

• Comprehensive testing environment for developers
• Testing SDK integration with live SafePassage APIs
• Validating both client-side (static site) and server-side (merchant) flows
• Testing various configuration options and edge cases
• Debugging integration issues

Quick Start

Prerequisites

• Node.js 18+
• SafePassage API keys (get from your dashboard)

Setup

1. Clone and navigate to the service:

   cd services/sdk-tester

2. Install dependencies:

   npm install

3. Configure environment:

   cp .env.example .env
   # Edit .env and add your SAFEPASSAGE_SECRET_KEY

4. Start the server:

   npm start
   # or for development with auto-reload:
   npm run dev

5. Open the testing interface:

   http://localhost:3456

Testing Interface Features

The main testing interface (index.html) provides comprehensive testing capabilities:

Basic Tests Tab

• Client-Side Flow: For static websites using public keys only
• Server-Side Flow: For merchant websites with backend validation
• Regional Compliance: Test different age and verification requirements
• External User ID: Test passing custom user identifiers

Advanced Tests Tab

• Session Management: Direct API session creation and validation
• Dashboard Configuration: Test dashboard settings vs overrides
• API Key Types: Understand public vs secret key behaviors
• URL Parameter Handling: Test special characters and edge cases

Security & Validation Tab

• Return URL Validation: Check parameters after redirect
• Session Validation: Server-side validation results
• PostMessage Security: For new tab mode
• Anti-Tampering Tests: Security validation scenarios

Error Handling Tab

• Invalid Configurations: Test error scenarios
• API Errors: Handle various API error responses
• Session Errors: Test expired/invalid sessions
• User Flow Errors: Cancellation and popup blocking

Configuration

Environment Variables

Create a .env file based on .env.example:

# Required: Your secret API key
SAFEPASSAGE_SECRET_KEY=sk_your_secret_key_here

# API endpoints (defaults to production)
PORTAL_API_URL=https://api.safepassageapp.com
VERIFY_UI_URL=https://av.safepassageapp.com

# Demo Site Configuration (optional)
DEMO_MODE=false  # Set to true to enable demo site mode
DEMO_PUBLIC_KEY=pk_demo_public_key_here  # Demo tenant public key
DEMO_SECRET_KEY=sk_demo_secret_key_here  # Demo tenant secret key

Demo Site Setup

To run as a demo site:

1. Create a dedicated demo tenant in your SafePassage dashboard
2. Set demo API keys in your .env file:

   DEMO_MODE=true
   DEMO_PUBLIC_KEY=pk_your_demo_public_key
   DEMO_SECRET_KEY=sk_your_demo_secret_key

3. Start the server - it will serve the demo interface by default
4. Access routes:
   • / - Demo landing page (when DEMO_MODE=true or hostname is demo.safepassageapp.com)
   • /test - Internal testing tool (always available)
   • /demo - Demo page (always available)
   • /demo/success - Success page after verification
   • /demo/cancelled - Cancellation page

Testing Against Local Services

For local development:

PORTAL_API_URL=http://localhost:3001
VERIFY_UI_URL=http://localhost:5173

How It Works

1. Server Component (server.js):

   • Proxies API calls to live SafePassage services
   • Manages API keys securely (secret key never exposed to client)
   • Serves the SDK files and testing interface

2. Client Interface (index.html):

   • Comprehensive testing UI for all SDK features
   • Real-time event logging
   • Test result tracking
   • Configuration management

API Endpoints

The server provides several endpoints for testing:

• POST /api/v1/sessions/create - Proxy to create sessions
• POST /api/v1/sessions/validate - Proxy to validate sessions
• POST /merchant/create-session - Simulates merchant server-side flow
• POST /merchant/validate-session - Simulates merchant validation
• GET /api/config - Server configuration status

Docker Support

The SDK tester is included in the monorepo Docker setup:

# Start all services including SDK tester
docker-compose up

# Access at http://localhost:3456

Demo Site Features

Analytics Tracking

The demo site tracks key events for conversion optimization:

• demo_started - When user clicks a verification option
• demo_completed - When verification completes successfully
• demo_cancelled - When user cancels verification
• demo_conversion - When user clicks CTAs (contact sales, view docs)

External User IDs

Demo sessions use specific patterns for tracking:

• Age Verification: demo_age_{timestamp}
• Identity Verification: demo_identity_{timestamp}

These IDs help track demo usage and conversions in your SafePassage dashboard.

Important Notes

• Live API Testing: This tool connects to real SafePassage APIs
• API Keys: Never commit your .env file with real API keys
• Security: The secret key is only used server-side, never exposed to the client
• SDK Source: Uses the built SDK from verify-ui/sdk/dist
• Demo Tenant: Use a dedicated tenant for demo to separate from production data

Troubleshooting

1. "API key not configured": Make sure you've set SAFEPASSAGE_SECRET_KEY in your .env file
2. "Cannot connect to API": Check that the API URLs are correct and services are running
3. "SDK not found": Build the SDK first: cd ../verify-ui && npm run build-sdk

Support

For issues or questions:

• Check the main project documentation
• Review the test results and event logs in the interface
• Ensure your API keys are valid and have the correct permissions