becomap 1.5.70 → 1.5.71

package/public/README.md

@@ -0,0 +1,902 @@
+# Becomap WebView Integration API Reference
+
+This document provides detailed interface specifications for the Becomap WebView integration, including public methods, callback events, input parameters, and payload structures for native mobile application integration.
+
+## 📋 Table of Contents
+
+- [Public Methods](#public-methods)
+- [Callback Events](#callback-events)
+- [Core Data Interfaces](#core-data-interfaces)
+- [Input Parameter Structures](#input-parameter-structures)
+- [Callback Payload Structures](#callback-payload-structures)
+- [Error Handling Interfaces](#error-handling-interfaces)
+- [Enums and Constants](#enums-and-constants)
+
+## 📚 Public Methods
+
+### Core Initialization
+
+#### `init(siteOptions)`
+Initializes the map with site configuration and authentication credentials.
+
+**Parameters:**
+- `siteOptions`: Object containing authentication and site configuration
+  - `clientId`: String - Client identifier for authentication
+  - `clientSecret`: String - Client secret for authentication
+  - `siteIdentifier`: String - Unique site identifier
+
+**Features:**
+- Input validation and pre-condition checks
+- Timeout handling for initialization operations
+- Automatic retry on transient failures
+- Progressive loading with status updates
+
+---
+
+### Floor and Location Management
+
+#### `getCurrentFloor()`
+Retrieves the currently displayed floor information.
+- **Returns:** Current floor data via `onGetCurrentFloor` callback
+- **Error Handling:** Returns null on failure with error notification
+- **Internal:** Handles async operations internally with Promise resolution
+
+#### `selectFloorWithId(floorId)`
+Switches the map to display a specific floor.
+- **Parameters:** `floorId` - String identifier of the target floor
+- **Validation:** Checks if floor exists before switching
+- **Events:** Triggers `onFloorSwitch` when successful
+
+#### `selectLocationWithId(locationId)`
+Selects and highlights a specific location on the map.
+- **Parameters:** `locationId` - String identifier of the target location
+- **Validation:** Validates location exists and is accessible
+- **Events:** Triggers `onLocationSelect` when successful
+
+---
+
+### Data Retrieval Methods
+
+#### `getCategories()`
+Retrieves all available location categories.
+- **Returns:** Array of category objects via `onGetCategories` callback
+- **Fallback:** Returns empty array on failure
+- **Caching:** Results are cached for performance optimization
+- **Internal:** Handles async operations internally with Promise resolution
+
+#### `getLocations()`
+Retrieves all locations from the current site.
+- **Returns:** Array of location objects via `onGetLocations` callback
+- **Filtering:** Automatically filters by current floor if applicable
+- **Performance:** Optimized for large datasets
+- **Internal:** Handles async operations internally with Promise resolution
+
+#### `getAmenities()`
+Retrieves all amenity locations from the current site.
+- **Returns:** Array of amenity location objects via `onGetAmenities` callback
+- **Categorization:** Groups amenities by type
+- **Accessibility:** Includes accessibility information
+- **Internal:** Handles async operations internally with Promise resolution
+
+#### `getAmenityTypes()`
+Retrieves available amenity types from the current site.
+- **Returns:** Array of amenity type objects via `onGetAmenityTypes` callback
+- **Real-time:** Updates reflect current availability
+- **Internal:** Handles async operations internally with Promise resolution
+
+#### `selectAmenities(type)`
+Selects amenities of a specific type on the map.
+- **Parameters:** `type` - BCSiteAmenity enum value (e.g., "RESTROOM", "ATM", "FOOD_COURT")
+- **Validation:** Validates amenity type exists
+- **Visual:** Highlights selected amenities on map
+
+#### `getSessionId()`
+Retrieves the current session identifier for personalization.
+- **Returns:** Session ID string via `onGetSessionId` callback
+- **Async:** Handles asynchronous session creation
+- **Retry:** Automatic retry on session creation failure
+
+#### `getHappenings(type)`
+Retrieves happenings/events of a specific type.
+- **Parameters:** `type` - BCHappeningType enum value
+- **Returns:** Array of happening objects via `onGetHappenings` callback
+- **Filtering:** Supports time-based and location-based filtering
+- **Internal:** Handles async operations internally with Promise resolution
+
+#### `getEventSuggestions(sessionId, answers)`
+Retrieves personalized event suggestions based on user preferences.
+- **Parameters:**
+  - `sessionId` - String: Current session identifier
+  - `answers` - Array: User preference answers
+- **Returns:** Suggestion array via `onGetEventSuggestions` callback
+- **AI-Powered:** Uses machine learning for personalization
+
+---
+
+### Camera and Viewport Control
+
+#### `focusTo(location, zoom, bearing, pitch)`
+Focuses the map on a specific location with smooth animation.
+- **Parameters:**
+  - `location`: Location object or identifier
+  - `zoom`: Optional number - Zoom level (default: current zoom)
+  - `bearing`: Optional number - Bearing/rotation in degrees
+  - `pitch`: Optional number - Pitch/tilt in degrees
+- **Animation:** Smooth camera transition with configurable duration
+- **Validation:** Validates location exists and is accessible
+
+#### `updateZoom(zoom)`
+Updates the map zoom level with bounds checking.
+- **Parameters:** `zoom` - Number: New zoom level (typically 1-22)
+- **Bounds:** Automatically constrains to valid zoom range
+- **Animation:** Smooth zoom transition
+
+#### `updatePitch(pitch)`
+Updates the map pitch (tilt) angle.
+- **Parameters:** `pitch` - Number: New pitch angle in degrees (0-60)
+- **Validation:** Constrains pitch to valid range
+- **3D Effect:** Enables 3D building visualization at higher pitches
+
+#### `updateBearing(bearing)`
+Updates the map bearing (rotation).
+- **Parameters:** `bearing` - Number: New bearing in degrees (0-360)
+- **Normalization:** Automatically normalizes bearing to 0-360 range
+- **Compass:** Updates compass indicator if present
+
+#### `setBounds(sw, ne)`
+Sets geographic bounds for the map view.
+- **Parameters:**
+  - `sw`: Array [lat, lng] - Southwest coordinate
+  - `ne`: Array [lat, lng] - Northeast coordinate
+- **Validation:** Validates coordinate format and bounds
+- **Fitting:** Automatically adjusts zoom to fit bounds
+
+#### `setViewport(options)`
+Sets the viewport with comprehensive options.
+- **Parameters:** `options` - BCMapViewOptions object
+  - `zoom`: Optional number - Zoom level (1-22)
+  - `pitch`: Optional number - Pitch/tilt angle (0-60 degrees)
+  - `bearing`: Optional number - Bearing/rotation (0-360 degrees)
+  - `center`: Optional array [lat, lng] - Center coordinates
+- **Animation:** Smooth transition to new viewport
+- **Validation:** Validates all parameters
+
+#### `resetDefaultViewport(options)`
+Resets the map to default viewport with optional overrides.
+- **Parameters:** `options` - Optional BCMapViewOptions overrides
+- **Memory:** Remembers original default settings
+- **Animation:** Smooth transition back to defaults
+
+---
+
+### Selection and Interaction
+
+#### `clearSelection()`
+Clears all current selections on the map.
+- **Visual:** Removes all selection highlights
+- **State:** Resets internal selection state
+- **Events:** Triggers selection change events
+
+#### `enableMultiSelection(val)`
+Enables or disables multi-selection mode.
+- **Parameters:** `val` - Boolean to enable/disable multi-selection
+- **Behavior:** Allows selecting multiple locations simultaneously
+- **UI:** Updates selection indicators accordingly
+
+---
+
+### Search Functionality
+
+#### `searchForLocations(query, callbackId)`
+Searches for locations with fuzzy matching and ranking.
+- **Parameters:**
+  - `query` - String: Search text (supports partial matches)
+  - `callbackId` - String: Unique identifier for request tracking
+- **Features:**
+  - Fuzzy text matching
+  - Relevance ranking
+  - Real-time suggestions
+- **Returns:** Results via `onSearchForLocations` callback with callbackId
+
+#### `searchForCategories(query, callbackId)`
+Searches for categories with intelligent matching.
+- **Parameters:**
+  - `query` - String: Search text
+  - `callbackId` - String: Unique identifier for request tracking
+- **Features:**
+  - Category hierarchy search
+  - Synonym matching
+  - Popularity ranking
+- **Returns:** Results via `onSearchForCategories` callback with callbackId
+
+---
+
+### Route Management
+
+#### `getRoute(startID, goalID, waypoints, routeOptions)`
+Calculates optimal route with advanced options.
+- **Parameters:**
+  - `startID` - String: Starting location identifier
+  - `goalID` - String: Destination location identifier
+  - `waypoints` - Optional array: Waypoint location identifiers
+  - `routeOptions` - Optional BCRouteOptions: Route calculation preferences
+- **Features:**
+  - Multiple route algorithms
+  - Accessibility considerations
+  - Real-time obstacle avoidance
+- **Returns:** Route segments via `onGetRoute` callback
+
+#### `showRoute(segmentOrderIndex)`
+Displays the calculated route with visual enhancements.
+- **Parameters:** `segmentOrderIndex` - Optional number: Order index of specific segment to display
+- **Behavior:** If no parameter provided, shows entire route; if segment order index provided, shows only that segment
+- **Visual:** Animated route line with directional indicators
+- **Interactive:** Clickable route segments for details
+- **Accessibility:** High contrast mode support
+
+#### `showStep(step)`
+Shows a specific step in the current route.
+- **Parameters:** `step` - Number: Step order index to display
+- **Visual:** Highlights current step with animation
+- **Audio:** Optional voice guidance integration
+
+#### `clearAllRoutes()`
+Clears all displayed routes from the map.
+- **Cleanup:** Removes all route visualizations
+- **Memory:** Frees route calculation resources
+- **State:** Resets route controller state
+
+---
+
+### Utility Functions
+
+#### `cleanup()`
+Performs comprehensive cleanup when WebView is destroyed.
+- **Resources:** Cleans up all event listeners and timers
+- **Memory:** Releases map and site objects
+- **Storage:** Clears temporary data and caches
+- **State:** Resets application to destroyed state
+
+#### `healthCheck()`
+Performs bridge connectivity health check.
+- **Returns:** Comprehensive health status via `onHealthCheck` callback
+- **Monitoring:** Updates bridge health metrics
+
+#### `getAppState()`
+Retrieves current application state and diagnostics.
+- **Returns:** Application state, bridge health, queue status via `onGetAppState` callback
+
+#### `recoverFromError()`
+Attempts to recover from error states.
+- **Recovery:** Resets error conditions and retries operations
+- **Queue:** Processes any pending operations
+- **Returns:** Recovery status via `onErrorRecovery` callback
+
+#### `getDebugInfo()`
+Provides comprehensive debugging information.
+- **Returns:** System state, failed operations, performance metrics via `onGetDebugInfo` callback
+- **Storage:** Includes localStorage diagnostic data
+
+---
+
+## 🎯 Callback Events
+
+### Core Map Events
+
+#### `onRenderComplete`
+Triggered when the map finishes rendering and is ready for interaction.
+
+**Payload Structure:**
+- `site`: Complete BCMapSite object with all site information
+- `timestamp`: Number - Unix timestamp when event occurred
+- `appState`: String - Current application state ("ready")
+
+**Usage:** Initialize UI elements, enable user interactions, start location services
+
+#### `onViewChange` (Throttled)
+Triggered when the map view changes (zoom, pan, rotation).
+*Note: Throttled to maximum 10 events per second to prevent flooding.*
+
+**Payload Structure:**
+- `viewOptions`: BCMapViewOptions object
+  - `zoom`: Number - Current zoom level
+  - `pitch`: Number - Current pitch/tilt angle
+  - `bearing`: Number - Current bearing/rotation
+  - `center`: Array [lat, lng] - Current center coordinates
+- `timestamp`: Number - Unix timestamp when event occurred
+
+**Usage:** Update navigation controls, sync with external map controls, track user interaction patterns
+
+#### `onLocationSelect`
+Triggered when a location is selected on the map.
+
+**Payload Structure:**
+- `locations`: Array of BCLocation objects
+  - `id`: String - Unique location identifier
+  - `name`: String - Location name
+  - `floor`: String - Floor identifier where location exists
+  - `category`: String - Category identifier
+  - `coordinates`: Array [lat, lng] - Geographic coordinates
+- `timestamp`: Number - Unix timestamp when event occurred
+
+**Usage:** Display location details, update navigation destination, show location-specific actions
+
+#### `onFloorSwitch`
+Triggered when the user switches between floors.
+
+**Payload Structure:**
+- `floor`: BCMapFloor object
+  - `id`: String - Unique floor identifier
+  - `name`: String - Floor display name
+  - `level`: Number - Floor level/elevation
+  - `buildingId`: String - Parent building identifier
+- `timestamp`: Number - Unix timestamp when event occurred
+
+**Usage:** Update floor selector UI, refresh location lists, update navigation context
+
+#### `onStepLoad`
+Triggered when a route step is loaded during navigation.
+
+**Payload Structure:**
+- `step`: BCRouteStep object
+  - `index`: Number - Step order index
+  - `instruction`: String - Human-readable navigation instruction
+  - `distance`: Number - Distance to next step in meters
+  - `duration`: Number - Estimated time to next step in seconds
+  - `coordinates`: Array [lat, lng] - Step coordinates
+- `timestamp`: Number - Unix timestamp when event occurred
+
+**Usage:** Display navigation instructions, update progress indicators, trigger voice guidance
+
+#### `onWalkthroughEnd`
+Triggered when a navigation walkthrough completes.
+
+**Payload Structure:**
+- `timestamp`: Number - Unix timestamp when walkthrough ended
+- `duration`: Number - Total walkthrough duration in milliseconds
+- `stepsCompleted`: Number - Total number of steps completed
+
+**Usage:** Show completion message, reset navigation UI, log navigation analytics
+
+---
+
+### Data Retrieval Callbacks
+
+#### `onGetCurrentFloor`
+Returns current floor information with enhanced details.
+
+**Payload Structure:**
+- `id`: String - Floor unique identifier
+- `name`: String - Floor display name
+- `level`: Number - Floor level (0 for ground floor)
+- `buildingId`: String - Parent building identifier
+- `isDefault`: Boolean - Whether this is the default floor
+- `bounds`: Object - Floor boundary coordinates
+
+#### `onGetCategories`
+Returns array of categories with hierarchy information.
+
+**Payload Structure:** Array of BCCategory objects
+- `id`: String - Category unique identifier
+- `name`: String - Category display name
+- `icon`: String - Icon identifier or URL
+- `parentId`: String|null - Parent category ID for hierarchy
+- `subcategories`: Array[String] - Child category IDs
+
+#### `onGetLocations`
+Returns array of locations with comprehensive data.
+
+**Payload Structure:** Array of BCLocation objects
+- `id`: String - Location unique identifier
+- `name`: String - Location display name
+- `category`: String - Category identifier
+- `floor`: String - Floor identifier
+- `coordinates`: Array [lat, lng] - Geographic coordinates
+- `isAccessible`: Boolean - Accessibility status
+- `amenities`: Array[String] - Available amenity types
+
+#### `onGetAmenities`
+Returns array of all amenity locations.
+
+**Payload Structure:** Array of BCLocation objects filtered for amenity locations
+
+#### `onGetAmenityTypes`
+Returns available amenity types information.
+
+**Payload Structure:** Array of BCSiteAmenity objects with availability status
+
+#### `onGetSessionId`
+Returns session identifier for personalization.
+
+**Payload Structure:** String - Unique session identifier
+
+#### `onGetHappenings`
+Returns array of happenings/events.
+
+**Payload Structure:** Array of BCHappenings objects
+- `id`: String - Happening unique identifier
+- `name`: String - Event name
+- `description`: String - Event description
+- `startDate`: String - ISO 8601 start date
+- `endDate`: String - ISO 8601 end date
+- `type`: BCHappeningType - Event type enum
+- `locationId`: String - Associated location ID
+
+#### `onGetRoute`
+Returns calculated route segments.
+
+**Payload Structure:** Array of BCRouteSegment objects with navigation data
+
+---
+
+### Search Callbacks
+
+#### `onSearchForLocations`
+Returns location search results with relevance scoring.
+
+**Payload Structure:**
+- `callbackId`: String - Request tracking identifier
+- `results`: Array of search result objects
+  - `id`: String - Location identifier
+  - `name`: String - Location name
+  - `relevanceScore`: Number - Relevance score (0-1)
+  - `matchType`: String - Type of match ("name", "category", etc.)
+  - `category`: String - Location category
+- `totalResults`: Number - Total number of results found
+- `searchTime`: Number - Search execution time in milliseconds
+
+#### `onSearchForCategories`
+Returns category search results with hierarchy.
+
+**Payload Structure:**
+- `callbackId`: String - Request tracking identifier
+- `results`: Array of search result objects
+  - `id`: String - Category identifier
+  - `name`: String - Category name
+  - `relevanceScore`: Number - Relevance score (0-1)
+  - `locationCount`: Number - Number of locations in category
+
+---
+
+### Error Handling
+
+#### `onError`
+Triggered when an error occurs with comprehensive context.
+
+**Payload Structure:**
+- `message`: String - Human-readable error message
+- `stack`: String - Error stack trace for debugging
+- `timestamp`: Number - Unix timestamp when error occurred
+- `operation`: String - Operation that caused the error
+- `attempt`: Number - Current retry attempt number
+- `maxRetries`: Number - Maximum retry attempts configured
+- `appState`: String - Current application state
+- `bridgeHealth`: Object - Bridge connectivity status
+  - `isConnected`: Boolean - Bridge connection status
+  - `lastHeartbeat`: Number - Last successful heartbeat timestamp
+- Additional operation-specific context fields
+
+**Error Categories:**
+- **Network Errors**: Connectivity and API issues
+- **Validation Errors**: Invalid parameters or state
+- **Timeout Errors**: Operations exceeding time limits
+- **Bridge Errors**: WebView communication issues
+
+---
+
+### Health and Monitoring Events
+
+#### `onHealthCheck`
+Response to health check requests with system status.
+
+**Payload Structure:**
+- `timestamp`: Number - Health check timestamp
+- `appState`: String - Current application state
+- `bridgeConnected`: Boolean - Bridge connectivity status
+- `mapViewReady`: Boolean - Map view initialization status
+- `siteLoaded`: Boolean - Site data loading status
+- `queueLength`: Number - Pending operations count
+- `lastHeartbeat`: Number - Last successful heartbeat timestamp
+
+#### `onGetAppState`
+Returns comprehensive application state information.
+
+**Payload Structure:**
+- `appState`: String - Current application state
+- `bridgeHealth`: Object - Bridge connectivity metrics
+- `queueStatus`: Object - Operation queue information
+- `performance`: Object - Performance metrics
+
+#### `onGetDebugInfo`
+Returns detailed debugging information for troubleshooting.
+
+**Payload Structure:**
+- `timestamp`: Number - Debug info generation timestamp
+- `appState`: String - Current application state
+- `bridgeHealth`: Object - Bridge connectivity status
+- `queueLength`: Number - Pending operations count
+- `hasMapView`: Boolean - Map view existence status
+- `hasSite`: Boolean - Site data loading status
+- `eventListeners`: Number - Active event listener count
+- `userAgent`: String - Browser user agent
+- `becomapLoaded`: Boolean - SDK loading status
+- `containerExists`: Boolean - Map container existence
+- `failedMessagesCount`: Number - Failed message count
+- `lastFailedMessage`: Object|null - Last failed message details
+
+#### `onErrorRecovery`
+Confirms successful error recovery attempt.
+
+**Payload Structure:**
+- `timestamp`: Number - Recovery attempt timestamp
+- `success`: Boolean - Recovery success status
+- `operationsRetried`: Number - Number of operations retried
+- `queueCleared`: Boolean - Whether operation queue was cleared
+
+#### `onCleanupComplete`
+Confirms successful resource cleanup.
+
+**Payload Structure:**
+- `timestamp`: Number - Cleanup completion timestamp
+- `resourcesFreed`: Array[String] - List of freed resource types
+- `listenersRemoved`: Number - Number of event listeners removed
+
+---
+
+## 📊 Core Data Interfaces
+
+### BCLocation Interface
+Represents a location within the map with comprehensive metadata.
+
+**Properties:**
+- `id`: String - Unique location identifier
+- `externalId`: String - External system identifier for cross-references
+- `name`: String - Human-readable location name
+- `type`: BCLocationType - Location type enum (AMENITIES, ENTRANCE, etc.)
+- `description`: String - Detailed location description
+- `amenity`: BCSiteAmenity - Associated amenity type if applicable
+- `phone`: Record<string, string> - Phone numbers by type (main, support, etc.)
+- `social`: Record<string, string> - Social media links by platform
+- `operationHours`: Array<BCOperationHour> - Operating hours by day
+- `links`: Array<BCLink> - Associated web links
+- `categories`: Array<BCCategory> - Location categories
+- `tags`: Array<string> - Searchable tags
+- `banner`: String - Banner image URL
+- `logo`: String - Logo image URL
+- `siblingGroups`: Array<BCSiblingGroup> - Related location groups
+- `topLocation`: Boolean - Whether location is featured/prominent
+- `showLogo`: Boolean - Whether to display logo on map
+- `floor`: BCMapFloor - Floor where location exists
+- `mapObject`: BCMapObject|null - 3D model information if available
+- `sortOrder`: Number - Display order priority
+
+### BCMapFloor Interface
+Represents a floor/level within a building.
+
+**Properties:**
+- `id`: String - Unique floor identifier
+- `name`: String - Full floor name (e.g., "Ground Floor")
+- `shortName`: String - Abbreviated name (e.g., "GF")
+- `elevation`: Number - Floor elevation/level number
+- `imageUrl`: String|null - Floor plan image URL
+- `viewPort`: BCMapViewOptions - Default viewport settings for this floor
+
+**Methods:**
+- `equals(floor: BCMapFloor): Boolean` - Compare floor equality
+
+### BCMapSite Interface
+Represents the entire site/venue with all metadata.
+
+**Properties:**
+- `id`: String - Unique site identifier
+- `siteName`: String - Site display name
+- `address`: String - Physical address
+- `city`: String - City name
+- `countryCode`: String - ISO country code
+- `postal`: String - Postal/ZIP code
+- `state`: String - State/province
+- `telephone`: String - Primary phone number
+- `tzId`: String - Timezone identifier
+- `utcOffset`: String - UTC offset
+- `link`: String - Official website URL
+- `type`: String - Site type classification
+- `buildings`: Array<BCBuilding> - Buildings within the site
+- `imageUrls`: SiteImageUrls - Associated image URLs
+- `operationHours`: Array - Site operating hours
+- `otherLanguages`: Array<BCMapLanguage> - Supported languages
+
+### BCCategory Interface
+Represents a location category with visual styling.
+
+**Properties:**
+- `id`: String - Unique category identifier
+- `name`: String - Category display name
+- `icon`: String|null - Icon URL or identifier
+- `color`: BCColor - Category color scheme
+- `externalId`: String - External system identifier
+- `iconName`: String - Icon name from default icon set
+
+### BCColor Interface
+Represents color information for categories and styling.
+
+**Properties:**
+- `rgba`: String - RGBA color value
+- `hex`: String - Hexadecimal color value
+- `opacity`: Number - Opacity value (0-1)
+
+### BCMapViewOptions Interface
+Configuration options for map viewport and camera settings.
+
+**Properties:**
+- `center`: BCMapCoordinateLike - Geographic center point [lat, lng]
+- `zoom`: Number - Zoom level (typically 1-22)
+- `pitch`: Number - Camera pitch/tilt angle in degrees (0-60)
+- `bearing`: Number - Camera bearing/rotation in degrees (0-360)
+- `background`: String - Map container background color
+
+### BCRouteStep Interface
+Represents an individual step in a navigation route.
+
+**Properties:**
+- `orderIndex`: Number - Step sequence number
+- `floor`: BCMapFloor - Floor where step occurs
+- `action`: BC_STEP_ACTION - Step action type
+- `direction`: BC_STEP_DIRECTION - Movement direction
+- `reference`: BC_STEP_POSITION - Positional reference
+- `referenceLocation`: BCLocation|null - Associated location
+- `distance`: Number - Distance to next step in meters
+
+### BCHappenings Interface
+Represents events, offers, or news items at the site.
+
+**Properties:**
+- `id`: String - Unique happening identifier
+- `name`: String - Event/offer name
+- `description`: String - Detailed description
+- `startDate`: String - ISO 8601 start date
+- `endDate`: String - ISO 8601 end date
+- `showDate`: String - Display date format
+- `externalId`: String - External system identifier
+- `siteId`: String - Associated site identifier
+- `locationId`: String - Associated location identifier
+- `images`: Array<string> - Image URLs
+- `type`: BCHappeningType - Happening type enum
+- `priority`: Number - Display priority
+- `customFields`: Record<string, any> - Additional custom data
+
+### BCOperationHour Interface
+Represents operating hours for locations or sites.
+
+**Properties:**
+- `opens`: String - Opening time (e.g., "09:00 AM")
+- `closes`: String - Closing time (e.g., "05:00 PM")
+- `dayOfWeek`: Array<string> - Applicable days
+
+### BCLink Interface
+Represents hyperlinks associated with locations.
+
+**Properties:**
+- `url`: String - Link URL
+- `label`: String - Link display label
+
+### BCSiblingGroup Interface
+Represents groups of related locations.
+
+**Properties:**
+- `label`: String - Group name
+- `siblings`: Array<string> - Related location identifiers
+
+### BCMapObject Interface
+Represents 3D model information for locations.
+
+**Properties:**
+- `modelPath`: String - 3D model file path
+- `rotation`: Number - Model rotation angle
+- `scale`: Number - Model scale factor
+
+---
+
+## 📝 Input Parameter Structures
+
+### Site Options (for `init` method)
+Configuration object for map initialization.
+
+**Structure:**
+- `clientId`: String - Client authentication identifier
+- `clientSecret`: String - Client authentication secret
+- `siteIdentifier`: String - Target site unique identifier
+
+### Route Options (for `getRoute` method)
+Configuration object for route calculation.
+
+**Structure:**
+- `maxDistanceThreshold`: Number - Maximum allowed route distance
+- `getAccessiblePath`: Boolean - Whether to prioritize accessible routes
+
+### Viewport Options (for `setViewport` and `resetDefaultViewport` methods)
+Camera and view configuration object.
+
+**Structure:**
+- `center`: Array [lat, lng] - Geographic center coordinates
+- `zoom`: Number - Zoom level (1-22)
+- `pitch`: Number - Camera tilt angle in degrees (0-60)
+- `bearing`: Number - Camera rotation in degrees (0-360)
+- `background`: String - Map container background color
+
+### Segment Order Index (for `showRoute` method)
+Identifier for targeting specific route segments.
+
+**Structure:**
+- `segmentOrderIndex`: Number - Order index of the target segment (matches BCRouteSegment.orderIndex property)
+- **Range:** Positive integers starting from 0
+- **Validation:** Must correspond to an existing segment in the current route
+
+---
+
+## 🔧 Enums and Constants
+
+### BCSiteAmenity Enum
+Predefined amenity types available at locations.
+
+**Values:**
+- `RESTROOM` - General restroom facility
+- `PRAYER_ROOM` - Designated prayer/meditation room
+- `WASHROOM_MEN` - Men's washroom
+- `WASHROOM_WOMEN` - Women's washroom
+- `ATM` - Automated Teller Machine
+- `FOOD_COURT` - Food court area
+- `INFORMATION_DESK` - Information/help desk
+- `PICKUP_POINT` - Pickup/drop-off point
+- `WASHROOM_FAMILY` - Family-friendly washroom
+- `WASHROOM_ACCESSIBLE` - Accessible washroom for disabled individuals
+
+### BCLocationType Enum
+Classification of location types.
+
+**Values:**
+- `AMENITIES` - Amenity/service location
+- `ENTRANCE` - Building/area entrance
+- `STORE` - Retail store location
+- `OFFICE` - Office/business location
+- `RESTAURANT` - Dining establishment
+- `SERVICE` - Service provider location
+
+### BCHappeningType Enum
+Types of events and happenings.
+
+**Values:**
+- `EVENT` - Scheduled event
+- `OFFER` - Promotional offer
+- `NEWS` - News announcement
+
+### BC_STEP_ACTION Enum
+Navigation step action types.
+
+**Values:**
+- `NONE` - No specific action
+- `DEPARTURE` - Starting point departure
+- `ARRIVALDESTINATION` - Final destination arrival
+- `ARRIVALWAYPOINT` - Waypoint arrival
+- `TURN` - Direction change
+- `SWITCHFLOOR` - Floor/level change
+
+### BC_STEP_DIRECTION Enum
+Navigation step direction indicators.
+
+**Values:**
+- `NONE` - No specific direction
+- `STRAIGHT` - Continue straight
+- `RIGHT` - Turn right
+- `SLIGHTRIGHT` - Slight right turn
+- `UTURNRIGHT` - U-turn right
+- `LEFT` - Turn left
+- `SLIGHTLEFT` - Slight left turn
+- `UTURNLEFT` - U-turn left
+- `UP` - Move upward (stairs/elevator)
+- `DOWN` - Move downward (stairs/elevator)
+
+### BC_STEP_POSITION Enum
+Positional reference for navigation steps.
+
+**Values:**
+- `NONE` - No specific position
+- `AT` - At a specific point
+- `BEFORE` - Before reaching a point
+- `AFTER` - After passing a point
+
+---
+
+## 🔗 Message Bridge Protocol
+
+### Message Format
+All communication between native code and WebView follows a standardized JSON format:
+
+**Structure:**
+```
+{
+  "type": "string",      // Message type identifier
+  "payload": object,     // Message data (varies by type)
+  "timestamp": number    // Unix timestamp
+}
+```
+
+### Bridge Health Monitoring
+The bridge includes built-in health monitoring with automatic recovery:
+
+- **Heartbeat System**: Regular connectivity checks
+- **Operation Queue**: Failed operations queued for retry
+- **Error Recovery**: Automatic retry with exponential backoff
+- **State Management**: Application state tracking and recovery
+
+### Performance Considerations
+- **Event Throttling**: ViewChange events limited to 10/second
+- **Memory Management**: Automatic cleanup of resources
+- **Queue Management**: Intelligent operation processing
+- **Error Handling**: Graceful degradation and recovery
+
+---
+
+## 📋 Integration Checklist
+
+### Pre-Integration Requirements
+- [ ] Valid Becomap client credentials
+- [ ] Site identifier and configuration
+- [ ] WebView-enabled mobile application
+- [ ] Network connectivity for API calls
+
+### Implementation Steps
+1. **Bundle Integration**: Include generated bundle files in app
+2. **WebView Configuration**: Enable JavaScript and configure message handlers
+3. **Message Handling**: Implement native message processing
+4. **Error Handling**: Set up error handling and recovery
+5. **Testing**: Verify all public methods and callbacks work correctly
+
+### Post-Integration Validation
+- [ ] Map initializes successfully with valid credentials
+- [ ] All callback events are received and processed
+- [ ] Error handling works correctly
+- [ ] Performance is acceptable for target devices
+- [ ] Memory usage is within acceptable limits
+
+---
+
+## 🔍 API Usage Patterns
+
+### Initialization Pattern
+1. Load WebView with bundle
+2. Call `init()` with site options
+3. Wait for `onRenderComplete` callback
+4. Begin using other API methods
+
+### Data Retrieval Pattern
+1. Call data retrieval method (e.g., `getLocations()`)
+2. Handle response via corresponding callback (e.g., `onGetLocations`)
+3. Process returned data in native code
+4. Update UI accordingly
+
+### Search Pattern
+1. Call search method with query and callback ID
+2. Handle results via callback with matching callback ID
+3. Display search results to user
+4. Handle user selection
+
+### Navigation Pattern
+1. Calculate route with `getRoute()`
+2. Handle route data via `onGetRoute` callback
+3. Display route with `showRoute()` (entire route) or `showRoute(segmentOrderIndex)` (specific segment)
+4. Navigate step-by-step with `showStep()`
+5. Handle step events via `onStepLoad` callback
+
+### Segment-Level Navigation Pattern
+1. Calculate route with `getRoute()`
+2. Handle route segments via `onGetRoute` callback
+3. Display specific segment with `showRoute(segmentOrderIndex)`
+4. Switch between segments using different order indices with `showRoute(segmentOrderIndex)`
+5. Show entire route again with `showRoute()` (no parameters)
+
+### Error Handling Pattern
+1. Implement `onError` callback handler
+2. Log error details for debugging
+3. Attempt recovery with `recoverFromError()` if appropriate
+4. Provide user feedback and fallback options
+5. Monitor bridge health with periodic `healthCheck()` calls