Launch Parameters Parsing

/**
 * Parse URL search params to extract VK Mini App launch parameters
 * Converts string values to appropriate types with validation
 * @param searchParams - URL search params string (e.g., window.location.search)
 * @returns Parsed launch parameters object with type-safe values
 */
function parseURLSearchParamsForGetLaunchParams(
  searchParams: string
): Partial<LaunchParams>;

interface LaunchParams extends GetLaunchParamsResponse {
  /** Chat ID if launched from chat context */
  vk_chat_id: string;
  /** Whether app is recommended (0 or 1) */
  vk_is_recommended: number;
  /** Profile ID context */
  vk_profile_id: number;
  /** Whether profile button should be shown (0 or 1) */
  vk_has_profile_button: number;
  /** Testing group ID if in testing mode */
  vk_testing_group_id: number;
  /** ODR (On-Demand Resources) enabled flag */
  odr_enabled: undefined | 1;
}

interface GetLaunchParamsResponse {
  /** User ID who launched the app */
  vk_user_id: number;
  /** VK application ID */
  vk_app_id: number;
  /** Community ID if launched from community */
  vk_group_id?: number;
  /** Platform identifier */
  vk_platform: EGetLaunchParamsResponsePlatforms;
  /** User's language preference */
  vk_language?: EGetLaunchParamsResponseLanguages;
  /** User's role in community context */
  vk_viewer_group_role?: EGetLaunchParamsResponseGroupRole;
  /** Whether user has installed the app (0 or 1) */
  vk_is_app_user?: 0 | 1;
  /** Whether notifications are enabled (0 or 1) */
  vk_are_notifications_enabled?: 0 | 1;
  /** Whether user added app to favorites (0 or 1) */
  vk_is_favorite?: 0 | 1;
  /** Launch timestamp */
  vk_ts: number;
  /** Referrer information */
  vk_ref?: string;
  /** Access token settings */
  vk_access_token_settings?: string;
  /** Cryptographic signature for verification */
  sign: string;
}

import { parseURLSearchParamsForGetLaunchParams } from "@vkontakte/vk-bridge";

// Parse current page URL parameters
const launchParams = parseURLSearchParamsForGetLaunchParams(window.location.search);

console.log('User ID:', launchParams.vk_user_id);
console.log('App ID:', launchParams.vk_app_id);
console.log('Platform:', launchParams.vk_platform);
console.log('Language:', launchParams.vk_language);

// Example URL:
// https://example.com/?vk_user_id=12345&vk_app_id=51665960&vk_platform=desktop_web&vk_language=en&sign=abc123

// Handle different launch contexts
if (launchParams.vk_group_id) {
  console.log('Launched from community:', launchParams.vk_group_id);
  console.log('User role:', launchParams.vk_viewer_group_role);
  showCommunityInterface(launchParams.vk_group_id);
}

if (launchParams.vk_chat_id) {
  console.log('Launched from chat:', launchParams.vk_chat_id);
  showChatInterface(launchParams.vk_chat_id);
}

if (launchParams.vk_profile_id) {
  console.log('Profile context:', launchParams.vk_profile_id);
  showProfileInterface(launchParams.vk_profile_id);
}

// User status checks
if (launchParams.vk_is_app_user === 1) {
  console.log('User has installed the app');
  showAdvancedFeatures();
} else {
  console.log('New user - show onboarding');
  showOnboarding();
}

if (launchParams.vk_is_favorite === 1) {
  console.log('App is in user favorites');
} else {
  console.log('Suggest adding to favorites');
  suggestAddToFavorites();
}

interface ParameterConversions {
  /** String to number conversion for numeric parameters */
  vk_user_id: number;
  vk_app_id: number;
  vk_group_id: number;
  vk_ts: number;
  vk_profile_id: number;
  vk_testing_group_id: number;
  vk_is_recommended: number;
  vk_has_profile_button: number;
  
  /** String to 0|1 conversion with validation */
  vk_is_app_user: 0 | 1;
  vk_are_notifications_enabled: 0 | 1;
  vk_is_favorite: 0 | 1;
  
  /** String values preserved as-is */
  sign: string;
  vk_chat_id: string;
  vk_ref: string;
  vk_access_token_settings: string;
  
  /** Enum validation for specific values */
  vk_language: EGetLaunchParamsResponseLanguages;
  vk_platform: EGetLaunchParamsResponsePlatforms;
  vk_viewer_group_role: EGetLaunchParamsResponseGroupRole;
  
  /** Special handling for ODR flag */
  odr_enabled: undefined | 1;
}

// The parser handles type conversion automatically
const params = parseURLSearchParamsForGetLaunchParams(
  '?vk_user_id=12345&vk_is_app_user=1&vk_language=en&odr_enabled=1'
);

// Types are correctly converted:
console.log(typeof params.vk_user_id);        // 'number'
console.log(typeof params.vk_is_app_user);    // 'number' (0 or 1)
console.log(typeof params.vk_language);       // 'string' (validated enum)
console.log(typeof params.odr_enabled);       // 'number' (1) or 'undefined'

// Invalid values are filtered out:
const invalidParams = parseURLSearchParamsForGetLaunchParams(
  '?vk_user_id=invalid&vk_language=invalid_lang&vk_is_app_user=maybe'
);

console.log(invalidParams.vk_user_id);        // undefined (invalid number)
console.log(invalidParams.vk_language);       // undefined (invalid enum)
console.log(invalidParams.vk_is_app_user);    // undefined (invalid 0|1)

enum SupportedParameters {
  // Numeric parameters
  'vk_ts' = 'timestamp',
  'vk_is_recommended' = 'recommendation_flag',
  'vk_profile_id' = 'profile_context',
  'vk_has_profile_button' = 'profile_button_flag', 
  'vk_testing_group_id' = 'testing_group',
  'vk_user_id' = 'user_identifier',
  'vk_app_id' = 'application_identifier',
  'vk_group_id' = 'community_identifier',
  
  // String parameters
  'sign' = 'cryptographic_signature',
  'vk_chat_id' = 'chat_context',
  'vk_ref' = 'referrer_information',
  'vk_access_token_settings' = 'token_permissions',
  
  // Special flag
  'odr_enabled' = 'on_demand_resources',
  
  // Toggle state parameters (0|1)
  'vk_is_app_user' = 'app_installation_status',
  'vk_are_notifications_enabled' = 'notification_permissions',
  'vk_is_favorite' = 'favorite_status',
  
  // Enum parameters with validation
  'vk_language' = 'user_language_preference',
  'vk_viewer_group_role' = 'community_role',
  'vk_platform' = 'client_platform'
}

// Example with all possible parameters
const fullUrl = `
?vk_user_id=12345
&vk_app_id=51665960
&vk_group_id=123456789
&vk_platform=desktop_web
&vk_language=en
&vk_viewer_group_role=admin
&vk_is_app_user=1
&vk_are_notifications_enabled=1
&vk_is_favorite=0
&vk_ts=1640995200
&vk_ref=menu
&vk_access_token_settings=friends,photos
&sign=abc123def456
&vk_chat_id=2000000001
&vk_profile_id=67890
&vk_has_profile_button=1
&vk_testing_group_id=999888777
&vk_is_recommended=1
&odr_enabled=1
`.replace(/\s+/g, '');

const allParams = parseURLSearchParamsForGetLaunchParams(fullUrl);

// All parameters are properly typed and converted
console.log('Complete launch context:', allParams);

interface ValidationBehavior {
  /** Invalid numeric values become undefined */
  numericValidation: 'undefined_on_invalid';
  
  /** Invalid enum values become undefined */
  enumValidation: 'undefined_on_invalid';
  
  /** Invalid toggle states (not 0 or 1) become undefined */
  toggleValidation: 'undefined_on_invalid';
  
  /** Parsing errors are caught and logged */
  errorHandling: 'warn_and_continue';
}

// Robust parameter parsing with fallbacks
function parseLaunchParamsWithFallbacks(searchParams: string) {
  try {
    const params = parseURLSearchParamsForGetLaunchParams(searchParams);
    
    // Provide fallbacks for critical parameters
    return {
      userId: params.vk_user_id || 0,
      appId: params.vk_app_id || 0,
      platform: params.vk_platform || EGetLaunchParamsResponsePlatforms.DESKTOP_WEB,
      language: params.vk_language || EGetLaunchParamsResponseLanguages.EN,
      isAppUser: params.vk_is_app_user === 1,
      notificationsEnabled: params.vk_are_notifications_enabled === 1,
      isFavorite: params.vk_is_favorite === 1,
      timestamp: params.vk_ts || Date.now() / 1000,
      signature: params.sign || '',
      
      // Optional context
      groupId: params.vk_group_id,
      chatId: params.vk_chat_id,
      profileId: params.vk_profile_id,
      viewerRole: params.vk_viewer_group_role,
      referrer: params.vk_ref,
      tokenSettings: params.vk_access_token_settings,
      
      // Flags
      isRecommended: params.vk_is_recommended === 1,
      hasProfileButton: params.vk_has_profile_button === 1,
      testingGroupId: params.vk_testing_group_id,
      odrEnabled: params.odr_enabled === 1
    };
  } catch (error) {
    console.error('Failed to parse launch parameters:', error);
    return null;
  }
}

// Usage with validation
const launchContext = parseLaunchParamsWithFallbacks(window.location.search);

if (!launchContext || !launchContext.userId || !launchContext.appId) {
  console.error('Invalid launch parameters');
  showError('Invalid app launch context');
} else {
  console.log('Valid launch context:', launchContext);
  initializeApp(launchContext);
}

// Complete launch parameter handling
async function handleAppLaunch() {
  // 1. Parse URL parameters
  const urlParams = parseURLSearchParamsForGetLaunchParams(window.location.search);
  
  // 2. Initialize bridge
  await bridge.send('VKWebAppInit');
  
  // 3. Get official launch parameters from bridge
  const bridgeParams = await bridge.send('VKWebAppGetLaunchParams');
  
  // 4. Compare and validate
  const isValidLaunch = validateLaunchParameters(urlParams, bridgeParams);
  
  if (!isValidLaunch) {
    console.error('Launch parameter mismatch');
    return;
  }
  
  // 5. Use merged context
  const launchContext = {
    ...urlParams,
    ...bridgeParams,
    // Additional parsed parameters from URL
    chatId: urlParams.vk_chat_id,
    profileId: urlParams.vk_profile_id,
    isRecommended: urlParams.vk_is_recommended === 1,
    odrEnabled: urlParams.odr_enabled === 1
  };
  
  return launchContext;
}

function validateLaunchParameters(urlParams: Partial<LaunchParams>, bridgeParams: GetLaunchParamsResponse): boolean {
  // Critical parameters must match
  const criticalFields = ['vk_user_id', 'vk_app_id', 'vk_platform', 'sign'] as const;
  
  return criticalFields.every(field => {
    const urlValue = urlParams[field];
    const bridgeValue = bridgeParams[field];
    
    if (urlValue !== undefined && bridgeValue !== undefined) {
      return urlValue === bridgeValue;
    }
    
    return true; // Allow if one is undefined
  });
}

// Initialize app with launch context
handleAppLaunch().then(context => {
  if (context) {
    startApplication(context);
  } else {
    showError('Failed to initialize app context');
  }
});