Fetch city location suggestions from AstroMatrix or Google Places API. Summary: Retrieves a list of possible birth location suggestions matching the provided query string. Uses Google Places Autocomplete API when useGoogleAPI is true, otherwise uses AstroMatrix API.

Fetch city locations from AstroMatrix API (default implementation)

Fetch city locations from Google Places Autocomplete API

Fetch detailed city information from AstroMatrix or Google Places Details API. Summary: Requests detailed metadata for a given town name (e.g., coordinates, timezone hints). Uses Google Places Details API when useGoogleAPI is true, otherwise uses AstroMatrix API.

Fetch city info from AstroMatrix API (default implementation)

Fetch city info from Google Geocoding API

Fetch timezone data from Google Timezone API or TimeZoneDB. Summary: Retrieves timezone information for a given geographic coordinate and timestamp. The implementation selects between Google Timezone API and TimeZoneDB based on the `useGoogleAPI` flag.

Get planet positions for ephemeris table (month view). Summary: Fetches daily planet positions for a given month and year. Returns positions for all planets (inner and outer) at midnight UTC for each day of the month.

Calculate chart positions by sending chart payload to the CalcPositions endpoint. Summary: Sends a ChartPayload to the astrology calculation endpoint and returns the computed chart data.

Reverse geocode coordinates to get formatted address/town name

Calculate horoscopes based on provided chart data. Summary: Sends computed chart data to the horoscope calculation endpoint to generate horoscope text/entries.

Generate AI-based report for a given chart. Summary: Sends a chart payload and desired report type to the AI report endpoint and returns the generated report content.

Dispose resources used by the AstroApiService. Summary: Placeholder for cleanup logic. Currently a no-op but provided for lifecycle parity.

Initialize deep link service (no-op on web)

Handle deep link (no-op on web)

Remove affiliate code

Update user info

Dispose (no-op on web)

Returns the singleton instance of [DeviceService].

Initialize device information by fetching the device ID and platform.

Determines and caches the device ID based on the current platform.

Retrieves the iOS vendor identifier using device_info_plus. Returns a fallback string on failure.

Retrieves the Android ID using the android_id plugin. Returns a fallback string on failure.

Returns a normalized platform name for the current OS.

Returns timezone information containing the timezone name and offset in minutes. The `timeZoneOffset` value is the negated offset in minutes from UTC.

Returns the singleton instance of [DeviceService].

Initialize device information by setting platform and generating device ID.

Generates a web-compatible device identifier. Uses a simple random ID for web sessions.

Returns "web" as the platform name.

Returns timezone information containing the timezone name and offset in minutes. The `timeZoneOffset` value is the negated offset in minutes from UTC.

Allow backend override for testing or alternative implementations

Generate a completion from a simple text prompt

Helper method for quick questions with default settings

Helper method for creative content generation

Helper method for analytical/factual responses

Translate text from one language to another If fromLanguage is null, auto-detects source language

Allow backend override for testing or alternative implementations

Generate a completion from a simple text prompt

Helper method for quick questions with default settings

Helper method for creative content generation

Helper method for analytical/factual responses

Translate text from one language to another If fromLanguage is null, auto-detects source language

Allow backend override for testing or alternative implementations

Generate a completion from a simple text prompt

Helper method for quick questions with default settings

Helper method for creative content generation

Helper method for analytical/factual responses

Translate text from one language to another If fromLanguage is null, auto-detects source language

=============================================================== CACHE EXPIRY HELPERS ===============================================================

Calculate expiry timestamp from duration Returns null if duration is null (no expiry)

Check if a record is expired

=============================================================== ADVANCED EXPIRY METHODS (for granular control) ===============================================================

Create record with specific expiry (bypasses defaultExpiry)

Update record and refresh its expiry time

=============================================================== STANDARD CRUD METHODS ===============================================================

Get all records for a parent key

Get single record by ID

Create a new record Uses JsonStorageService.defaultExpiry for cache expiry (null = never expires)

Update existing record Keeps existing expiry unless record is new/recreated

Delete record (soft delete - marks as deleted)

=============================================================== INVALIDATION METHODS ===============================================================

Invalidate all records for a specific parent key Example: When user's birth data changes, invalidate all their charts

Invalidate specific record by ID Example: Invalidate a single chart

Invalidate all records in a namespace Use sparingly! Only for logout or complete refresh

Invalidate records older than a certain age Example: Delete transits older than 30 days

Invalidate (soft delete) expired records Returns the count of records invalidated

=============================================================== SYNC METHODS ===============================================================

Get unsynced records for background sync

Mark record as synced (optionally replace local ID with server ID)

OPTIMIZED: Sync records from server using batch operations This prevents database locks by using transactions Uses JsonStorageService.defaultExpiry for cache expiry

=============================================================== CLEANUP METHODS ===============================================================

Hard delete synced deletions (cleanup after successful sync)

Hard delete expired records (cleanup) Returns the count of records deleted

Clear all records for a namespace (hard delete)

Clear all data (for testing or logout)

=============================================================== STATISTICS & DEBUGGING ===============================================================

Get statistics for debugging

=============================================================== CACHE EXPIRY HELPERS ===============================================================

=============================================================== STANDARD CRUD METHODS ===============================================================

Deletes the oldest records in a namespace based on created_at timestamp

Returns the singleton instance of [LanguageService].

Initializes the service by loading the saved language from persistent storage and ensuring the corresponding translation table is available.

Sets the active language, persists it, and reloads the translation table.

Ensures the translation table for the current language is loaded; no-op if already available.

Fetches the language table for the current language from the remote API and caches it for synchronous lookups; does nothing for English.

Loads translation table from local storage cache.

Saves translation table to local storage cache.

Clears the cache for a specific language or all languages.

Loads the skip list from persistent storage. Called during initialization to restore previously saved skip list.

Saves the skip list to persistent storage. Called automatically whenever the skip list is modified.

Checks if a text should be skipped from translation. Returns true if the text matches patterns that indicate it shouldn't be translated (e.g., dates, numbers, URLs, emails, names, etc.)

Adds a string to the skip list so it will never be translated. Useful for names, proper nouns, or other content that should remain unchanged. The skip list is automatically persisted to storage.

Adds multiple strings to the skip list. The skip list is automatically persisted to storage.

Removes a string from the skip list. The skip list is automatically persisted to storage.

Clears the entire skip list. The skip list is automatically persisted to storage.

Returns a translated string for [name] using the cached language table or the original text if no translation exists. If translation is missing, triggers a background GPT translation that will be available on next call. Supports simple transformation modes via [type] ('split' to translate each space-separated token, 'time' to translate only the first token). **Performance Note:** This method NEVER calls the API. It only reads from the in-memory cache (_languageItems). The cache is: - Loaded from local storage on app startup (fast) - Fetched from API only if cache is missing or stale (>7 days) - Updated in memory and persisted to storage after API fetch You can call getLang() thousands of times per second with zero API calls.

Triggers a background GPT translation without blocking. Uses debouncing and batching to optimize API calls.

Processes the translation queue by batching all pending strings into one API call. Respects rate limiting to prevent API overload.

Performs batch GPT translation for multiple strings in one API call. This is much more efficient than individual calls.

Creates a batch translation prompt that GPT can process. Format: "Translate these English strings to [Language]. Return JSON format: {\"string1\": \"translation1\", \"string2\": \"translation2\"}"

Parses the batch translation response from GPT. Expects JSON format: {"original": "translation", ...} Handles various response formats GPT might return.

Fallback: Translate strings individually if batch fails. Only used as last resort.

Performs the actual GPT translation and caches the result. @deprecated Use _performBatchGPTTranslation instead for better performance.

Clears the GPT translation cache for the current language

Cancels any pending translation requests and clears the queue. Useful when language changes to prevent stale translations.

Global convenience that delegates to the singleton [LanguageService] for a synchronous translation lookup. Automatically triggers background GPT translation for missing keys.

Factory that returns the singleton [LoggingService] instance.

Sends an error or info log to the Node API or base API depending on `useNode`. Short summary: constructs a payload with uid, message, info, platform and timestamp and POSTs it to the logging endpoint.

Convenience helper that logs an informational message. Calls [logError] with "INFO: " prefixed to the message.

Prints a debug-only message to the console when in debug mode. Short summary: outputs a debug-only message using `debugPrint` when `kDebugMode` is true. Does not perform network I/O.

Static helper to log ad-specific errors under the 'ads' user/category.

Static helper to log ad-specific informational messages under the 'ads' category.

Debug-only ad logging that prints JSON-encoded data when in debug mode.

Logs a metric event with name, type, value, and optional labels to the metrics endpoint. Short summary: builds an event payload and POSTs it to the metrics update endpoint.

Convenience method for logging counter metrics (delegates to [logEvent]).

Convenience method for logging gauge metrics (delegates to [logEvent]).

Get house system display name from code

Build payload from UserProfile(s) for self or relationship charts Parameters: - user1: Primary user (required) - prefs: Chart calculation preferences (house system, orbs, etc.) - chartType: Type of chart ('self', 'relationship', 'birthchart', etc.) - user2: Secondary user for relationship charts (optional) - transitDate: Date for transit calculations (optional) - transitLocation: Location for transit calculations (optional) - relocationLat, relocationLng, relocationTown: For relocation charts (optional) Returns: ChartPayload ready for API submission

Build date2 for relocation charts: location-only (lat, lng, town). The API uses date1 for birth moment (planets) and date2 for relocation location (houses/angles).

Build payload from BirthForm for chart creation/preview Used when creating a new user or previewing a chart from form data before saving the user profile. Parameters: - form: Birth form data (name, date, time) - location: Birth location data - prefs: Chart calculation preferences - transitDate: Optional transit date - transitLocation: Optional transit location Returns: ChartPayload ready for API submission

Build payload for current planets (no birth data required) Shows current planetary positions without reference to a birth chart. Parameters: - prefs: Chart calculation preferences - date: Date/time for planet positions (defaults to now) - location: Location for calculations (optional) Returns: ChartPayload for current planets

Convert UserProfile to ChartDate format for API payload Extracts all necessary birth data from user profile and formats it according to API requirements. Uses web-compatible format for fullDateStr. Optional location overrides allow changing location without modifying the user profile (useful for relocation charts).

Convert UserProfile to ChartDate format for date2 (minimal fields like web) Web's date2 doesn't include: type, timeHour, timeMinute, timePM, dst, mainUser, selectedTown

Build fullDateStr in web-compatible format Format: "January 11th 2000 5:00 PM" (note: double space before year)

Convert BirthForm + Location to ChartDate format for API payload Parses form data (YYYY-MM-DD date format, various time formats) and combines with location data to create complete ChartDate.

Build transit date ChartDate from DateTime and optional Location Used for transit charts, current planets, progressed charts, etc. Uses 24-hour time format for transit dates.

Build fullDateStr for transit date in web-compatible format Format: "December 24th 2025 12:09" (note: double space before year, 24h time)

Get human-readable type name for chart type

Get API path for chart type

Get house system display name from code

Build payload from UserProfile(s) for self or relationship charts Parameters: - user1: Primary user (required) - prefs: Chart calculation preferences (house system, orbs, etc.) - chartType: Type of chart ('self', 'relationship', 'birthchart', etc.) - user2: Secondary user for relationship charts (optional) - transitDate: Date for transit calculations (optional) - transitLocation: Location for transit calculations (optional) - relocationLat, relocationLng, relocationTown: For relocation charts (optional) Returns: ChartPayload ready for API submission

Build date2 for relocation charts: location-only (lat, lng, town). The API uses date1 for birth moment (planets) and date2 for relocation location (houses/angles).

Build payload from BirthForm for chart creation/preview Used when creating a new user or previewing a chart from form data before saving the user profile. Parameters: - form: Birth form data (name, date, time) - location: Birth location data - prefs: Chart calculation preferences - transitDate: Optional transit date - transitLocation: Optional transit location Returns: ChartPayload ready for API submission

Build payload for current planets (no birth data required) Shows current planetary positions without reference to a birth chart. Parameters: - prefs: Chart calculation preferences - date: Date/time for planet positions (defaults to now) - location: Location for calculations (optional) Returns: ChartPayload for current planets

Convert UserProfile to ChartDate format for API payload Extracts all necessary birth data from user profile and formats it according to API requirements. Uses web-compatible format for fullDateStr. Optional location overrides allow changing location without modifying the user profile (useful for relocation charts).

Convert UserProfile to ChartDate format for date2 (minimal fields like web) Web's date2 doesn't include: type, timeHour, timeMinute, timePM, dst, mainUser, selectedTown

Build fullDateStr in web-compatible format Format: "January 11th 2000 5:00 PM" (note: double space before year)

Convert BirthForm + Location to ChartDate format for API payload Parses form data (YYYY-MM-DD date format, various time formats) and combines with location data to create complete ChartDate.

Build transit date ChartDate from DateTime and optional Location Used for transit charts, current planets, progressed charts, etc. Uses 24-hour time format for transit dates.

Build fullDateStr for transit date in web-compatible format Format: "December 24th 2025 12:09" (note: double space before year, 24h time)

Get human-readable type name for chart type

Get API path for chart type

Get the active user's profile ID. Uses HoroscopeService.user1 (currently selected user) if available, falls back to the main user's profileID from storage.

Initialize all preferences with defaults on first app start

Upsert preferences (merge incoming with existing)

Set preference that works even when not logged in (mainly for language)

Save preference locally and sync to server

Sync preference to WebView

Notify listeners that a preference changed Replaces aggressive cache invalidation

Invalidate chart cache if preference affects chart calculations DEPRECATED: Now handled via preferenceChanges stream and constraint-based keys

Get all preferences for current user

Get all preferences for current user

Delete a specific preference

Sync from server FIXED: Uses ApiResult properties

Force sync unsynced preferences to server

Bulk update multiple preferences

Clear all preferences for current user

Export all preferences as JSON

Import preferences from JSON

Normalize raw value to expected type Handles legacy cases where server has "true", "6.0", "1" as strings

Initializes and connects the socket to the server and registers the given user.

Emits a `new_message` event with the provided payload to the server.

Registers a callback for incoming `message_received` events from the server.

Disconnects the socket and releases network resources.

Factory constructor returning the singleton AdsService instance.

Initialize the ads service This should be called before any ads are displayed. For paid users, ads are disabled immediately without any flicker.

Refreshes ad status based on comprehensive subscription info

Load ads state from SharedPreferences

Temporarily force hide or show ads (e.g., during splash screen).

Enable or disable ads

Hide all ads (called when user subscribes)

Dispose all ad objects

Load persistent global banner ad

Load and show banner ad (Legacy/Local)

Load and show interstitial ad

Load rewarded interstitial ad

Show rewarded interstitial ad

Check if ads should be shown based on web app request

Update user info

Log error to server

Handle load ad error

Handle show ad error

Dispose all resources

Logs a screen view safely.

Logs when main user (profileID) is missing but users exist

Logs when main user (profileID) is invalid (doesn't match any user)

Logs when main user is successfully auto-set

Logs main user validation check results

Call this on app start to increment session count

Check if we should show the review prompt Returns true if conditions are met

Schedule the review prompt to show after delay

User chose to rate now - open the store

User chose "Remind me later" - reset counter

User chose "Already reviewed" - never show again

Reset all review state (for testing)

Validates birth information by calculating a chart and extracting the Big Three. Uses ChartService.calculatePositionsForForm() which doesn't require a UserProfile.

Quickly checks whether the provided form and location appear complete for submission.

Validates an ISO-8601 date string for birth date constraints.

Validates a time string in HH:mm format.

Validates the overall birth form for required fields.

Get items for a category Used by ItemCategoryCtrl equivalent in Flutter Now with 14-day caching for improved performance

Get items from cache

Add items to cache with 14-day expiry

Clear all cached category items

Get items for a category Used by ItemCategoryCtrl equivalent in Flutter Now with 14-day caching for improved performance

Get items from cache

Add items to cache with 14-day expiry

Clear all cached category items

Initialize once on app start

Render a single chart

Render multiple pattern charts

Build pattern config - MATCHES NORMAL CHARTS

Build pattern astro data

Generate default houses

Get display label for a chart type Uses the displayName getter from ChartType enum

Build chart render config from chart type and screen size

Transform raw chart result into display-ready planet data [coordDisplayFormat] 'decimals' (e.g. 15.5°) or 'degrees_minutes' (e.g. 15°30')

Transform transit planets with display data [coordDisplayFormat] 'decimals' or 'degrees_minutes'

Transform houses with display data

Build aspect grid for display (full matrix) Builds from transitData array to match Angular structure: planets[i].aspects[j] = { Aspect, Orb, Item }

Get aspect grid for first 10 planets only (for compact display)

Get aspect grid for asteroids with specific horizontal/vertical layout Columns (horizontal): Asteroids only (Lilith through Psyche) Rows (vertical): All planets + asteroids (Sun through Psyche) This allows asteroid-to-planet aspects (e.g. Chiron conjunct Sun) to appear An aspect is placed if at least one of its planets is an asteroid

Get horizontal asteroid planets for grid columns

Get vertical asteroid planets for grid rows

Get chart titles based on chart type

Get chart titles with user names for synastry charts

Check if chart type should show transits

Check if chart type should show houses

Check if chart type should show declinations

Check if chart type needs second user

Calculate image width based on screen width

Format declination for display

Format house number as ordinal

Get aspect color for display

Get aspect symbol for display

Get planet image URL

Get sign image URL

Get aspect image URL

Get pattern formations as typed models

Render all aspect patterns from chart data

Check if patterns exist

Get pattern count

Clear pattern cache

Open component view - handles everything Central method for opening component screen from anywhere in the app. Creates MatrixItem and navigates to ComponentScreen. Example: ```dart ComponentService.openComponentView( context, componentName: 'Sun', category: 'Zodiac Planets', ); ```

Create a MatrixItem for navigation to ComponentScreen Helper method to create properly formatted MatrixItem objects for use with ComponentScreen navigation. Example: ```dart final item = ComponentService.createMatrixItem( componentName: 'Sun', category: 'Zodiac Planets', ); Navigator.push( context, MaterialPageRoute( builder: (context) => ComponentScreen(matrixItem: item), ), ); ```

Get component data with automatic traits parsing ✅ Returns both component data AND parsed traits in a single call ✅ Delegates to TarotService for tarot-related categories

Parse traits from GetComponent API response ✅ Automatically called by getItem()

Transform flat array API response into grouped structure ✅ FULLY DYNAMIC - automatically handles ANY trait category from API ✅ No hardcoded categories - add new categories in database without code changes

Get image URL for component ✅ Delegates to ComponentImageHelper for unified image handling Supports both standard components and tarot cards

Increment session count - call on app launch (after first time) This should be called from main.dart or startup_service

Record a component view and check if content should be gated Returns true if content is now gated

Check if content is currently gated (without recording a view)

Ungate content after watching an ad This resets the view counter for gating purposes

Ungate content permanently after purchase

Check if user is a paid user

Refresh paid status (useful after login or purchase)

Reset all gating state (for testing or user request)

Get debug info for logging

Planets currently transiting through signs. Matches the legacy JS filter: Forecasts category, hash contains 'short', excludes Retrograde and Moon items. Sorted by begins date.

Get glossary terms Endpoint: /help/get?type=Glossary Now with 14-day caching for improved performance

Get terms from cache

Add terms to cache with 14-day expiry

Clear cached glossary terms

Search horoscope items Endpoint: /API/Astrology/GetHoroscopeItems?search={query}

Get glossary terms Endpoint: /help/get?type=Glossary Now with 14-day caching for improved performance

Get terms from cache

Add terms to cache with 14-day expiry

Clear cached glossary terms

Search horoscope items Endpoint: /API/Astrology/GetHoroscopeItems?search={query}

Show help for a specific page/section/type Endpoint: /help/get?page={page}&section={section}&type={type} Now with 14-day caching for improved performance

Get help from cache

Add help to cache with 14-day expiry

Clear cached help data

Plug-and-play helper for showing help anywhere in the app

Graceful fallback required by the card

Initialize the service singleton. Safe to call multiple times - only initializes once. Call this early in main() before runApp().

Internal initialization - loads previously saved users and starts transit date refresh timer.

Persist user1 ID to preferences.

Persist user2 ID to preferences.

Load the default user as user1 when no user1 is set. Falls back to: main user (profileID) -> first available user

Ensure user1 is loaded before accessing charts/reports. If no user1 is set, loads the default user (main user or first available). Returns true if user1 is available after this call.

Set primary user for calculations.

Set secondary user for relationship calculations.

Set transit date for transit calculations. NOTE: Does NOT clear caches - date is part of cache key, so different dates use different cache entries. This allows bidirectional navigation (forward/back) to reuse cached data.

Need to review cleanup changes

Clear secondary user.

Clear both users (useful for logout scenarios).

Apply visibility preferences to chart data before rendering Uses ViewConstraints for consistent filtering across all displays: - Chart tables - Aspect grids - Matrix items - Any derived displays View constraints NEVER affect cache - they are applied post-fetch. Usage: ```dart final chartData = await calculateChart(...); final filteredData = await HoroscopeService.applyChartPreferences(chartData); final pngBytes = await renderer.renderChart(filteredData, config); ```

Load chart calculation preferences from PreferenceService.

Calculate chart positions (planets, houses, aspects). Uses current user1 and optionally user2/transitDate. For relocation charts, pass relocationLat/relocationLng/relocationTown. Results are cached by user ID, date, AND all calculation constraints. This allows instant switching between configurations without cache invalidation.

Calculate positions directly from BirthForm and Location. Used for birth validation before a UserProfile is created. Does not use or affect internal state (user1/user2). Results are NOT cached (no user ID to cache against).

Get ephemeris data (planet positions for a month)

Calculate horoscopes with interpretations.

Internal method to fetch horoscopes from API Extracted to allow request deduplication

Synchronously retrieve horoscope data from memory cache if available. Matches by user ID and type (e.g. 'self', 'relationship').

Synchronously retrieve chart positions from memory cache if available.

Synchronously retrieve extended moon info.

Synchronously retrieve planet hour info.

Synchronously retrieve life path.

Synchronously retrieve specific planet.

Invalidate all cached data for a user. Call this when user's birth data changes.

Invalidate old transit data.

Build cache key from current state and calculation constraints. The cache key includes ALL calculation-affecting constraints so that: - Users can switch instantly between house systems, sidereal/tropical, etc. - Each configuration has its own cached result - We never need to invalidate cache on constraint change (new key = new entry)

Synchronous cache key builder (uses cached constraints if available) Falls back to simple key if constraints not loaded yet

Build ChartPayload from current state. Build ChartPayload from current state.

Find a chart by its type from the charts list Searches for a chart matching the target type by checking type fields. Returns null if chart not found.

Get chart by type or fall back to index Tries to find chart by type first, falls back to index if not found.

Get LifePath numerology data Parameters: - fromChart: Which chart to get LifePath from - ChartType.birth: Permanent birth life path (default) - ChartType.transit: Daily number (birth + transit date)

Get Big Three (Sun, Moon, Ascendant) from birth chart (synchronous, memory-only) Returns BigThree with Placement objects for sun, moon, and ascendant Returns null if any of the three are missing or not in memory cache

Get Big Three (Sun, Moon, Ascendant) from birth chart (async, may call API) Returns BigThree with Placement objects for sun, moon, and ascendant Returns null if any of the three are missing WARNING: This method calls calculateHoroscopes API if data not cached. Prefer using getBigThreeSync() or user.bigThree when possible.

Get extended moon information (always from transit/daily chart)

Get planetary hours data (always from transit/daily chart)

Get chakra balance data

Get all planets Parameters: - fromChart: Which chart type to get planets from - ChartType.birth: Natal planet positions - ChartType.transit: Current planet positions with transit houses (default)

Get specific planet by name

Get Mayan astrology data (always from birth chart)

Get profection data (from transit chart)

Get psychology analysis (short version)

Returns a random ad filtered by type. Call this in widget's initState to get a fresh random ad each time the page is created. Returns null if user is subscribed (paid) - no in-house ads for paid users.

Returns a random item content ad (uses the dedicated ItemContent endpoint) Returns null if user is subscribed (paid).

Returns a random tarot ad Returns null if user is subscribed (paid).

Returns promo text Returns null if user is subscribed (paid).

Returns all ads of a given type Returns empty list if user is subscribed (paid).

Fetches the live server configuration from the node endpoint, compares it with stored configuration and optionally saves or navigates based on device/SDK constraints and detected changes.

Loads the last saved LiveServerData from SharedPreferences if present.

Persists the given LiveServerData to SharedPreferences as JSON.

Retrieves the daily splash image and quote from the API and stores them in SharedPreferences and global variables for immediate use before app bootstrapping.

Validates an in-app purchase receipt with the backend and logs the validation steps; returns the backend response map on success.

Sends purchase information to the backend, optionally including affiliate details, and logs execution traces for debugging.

Fetches a list of verified affiliate codes from the backend and returns an empty list on error or unexpected response formats.

Fetch live server configuration (web-safe version)

Fetch splash info (web-safe version)

Validate purchase with server (not available on web)

Post payment info (not available on web)

Sync payments (web-safe version)

Get verified affiliate codes (web-safe)

Check if location service is enabled

Check and request location permissions

Get current GPS coordinates

Complete location flow: check service, permissions, get location

Get current GPS position (just coordinates, no WebView)

Reverse geocode coordinates to get town name

Search for locations with debouncing

Search for locations (no debouncing)

Select location from suggestion

Select location and get full details with timezone

Cancel pending searches

Get all conversations for the current user

Get messages between two users

Validate/approve a user by email

Get current user ID from storage

Format timestamp for display

Send a message and return list of messages to add to UI For support: calls HTTP endpoint and returns [userMessage, autoResponse] For regular: emits via socket and returns [userMessage]

Helper: Navigate directly to a conversation with any user For support: userId = 'support@astromatrix.org' For regular users: userId = their actual ID

Update a Prometheus metric Endpoint: POST /events/metrics/updateMetric [name] - Metric name [type] - Metric type: 'gauge' or 'counter' [value] - Numeric value to set/increment [labels] - Optional labels for the metric

Send a gauge metric (sets absolute value)

Send a counter metric (increments by value)

Ping the server to mark user as online Endpoint: POST /events/metrics/pingonline [uid] - User ID to mark as active Returns the total number of active users

Get current count of users online Endpoint: GET /events/metrics/usersonline Returns the number of active users

Track meditation session start

Track meditation session completion

Track API errors

Track feature usage

Track tarot trait fetching

Helper to get the screen name from a route

Start timer for a screen

Stop timer for a specific screen

Mark the reading as completed and send metrics

Mark the reading as canceled / incomplete

Calculate duration and send metrics

Update a Prometheus metric Endpoint: POST /events/metrics/updateMetric [name] - Metric name [type] - Metric type: 'gauge' or 'counter' [value] - Numeric value to set/increment [labels] - Optional labels for the metric

Send a gauge metric (sets absolute value)

Send a counter metric (increments by value)

Ping the server to mark user as online Endpoint: POST /events/metrics/pingonline [uid] - User ID to mark as active Returns the total number of active users

Get current count of users online Endpoint: GET /events/metrics/usersonline Returns the number of active users

Track meditation session start

Track meditation session completion

Track API errors

Track feature usage

Track tarot trait fetching

Helper to get the screen name from a route

Start timer for a screen

Stop timer for a specific screen

Mark the reading as completed and send metrics

Mark the reading as canceled / incomplete

Calculate duration and send metrics

Update a Prometheus metric Endpoint: POST /events/metrics/updateMetric [name] - Metric name [type] - Metric type: 'gauge' or 'counter' [value] - Numeric value to set/increment [labels] - Optional labels for the metric

Send a gauge metric (sets absolute value)

Send a counter metric (increments by value)

Ping the server to mark user as online Endpoint: POST /events/metrics/pingonline [uid] - User ID to mark as active Returns the total number of active users

Get current count of users online Endpoint: GET /events/metrics/usersonline Returns the number of active users

Track meditation session start

Track meditation session completion

Track API errors

Track feature usage

Track tarot trait fetching

Helper to get the screen name from a route

Start timer for a screen

Stop timer for a specific screen

Mark the reading as completed and send metrics

Mark the reading as canceled / incomplete

Calculate duration and send metrics

Get extended moon information Fetches current moon phase, next moon events, VOC/OOB status, etc. Data comes from the transit chart in HoroscopeService. Returns null if data unavailable or on error.

Get just the current moon phase info

Get next moon phase event

Get next lunar event (eclipse, etc)

Check if moon is currently void of course

Check if moon is currently out of bounds

Calculate moon width based on perigee percentage (matching AngularJS logic)

Determine if this is a Super Moon (>90% perigee)

Determine if this is a Micro Moon (<10% perigee)

Get moon special type (Super/Micro/null)

Build full moon string like "Full Moon in Aries"

Load product configuration from assets

Build lookup maps for O(1) access

Fallback to hardcoded config if JSON loading fails

Get all product IDs that should be fetched from store

Get product configuration by ID

Get discount product ID for a regular product

Check if a product has a discount version

Get all active products (non-legacy) [excludeDiscounts] - if true, excludes discount products from the list

Get only regular (non-discount) products

Get products sorted by display order

Get products filtered by type

Get subscription products only

Get lifetime products only

Get discount products only

Convert icon name string to IconData

Convert ProductConfig to SubscriptionProductConfig (for compatibility)

Get display order for a product ID

Reload configuration (useful for testing or hot reload)

Factory constructor that returns the singleton instance.

Initialize the purchase service and connect to the platform store.

Load previously processed purchase IDs from SharedPreferences.

Persist a purchase ID to the processed set and SharedPreferences.

Remove a purchase ID from the processed set (for retry scenarios).

Save current processed IDs set to SharedPreferences.

Load product IDs from JSON config file

Update the cached user ID (useful after login changes).

Check if a userId is an anonymous/device-generated ID (not a real email). These IDs start with 'app-' and are assigned before the user logs in. They should NEVER be used for payment processing.

Aggressively recover userId from all available sources. This is the safety net that prevents payments from being lost. Recovery order: 1. SharedPreferences (cached_user_id) 2. WebView localStorage (userid)

Connect to the platform store, subscribe to purchase stream, and fetch available products and past purchases.

Process incoming purchase updates from the platform purchase stream. Validates receipts (iOS), posts payment info to backend, completes purchases, and logs events; handles pending, restored, error, and purchased statuses.

Convert a PurchaseDetails object into a compact JSON string for storage.

Handle IAP errors (currently logs to debug output).

Initiate purchase flow for a non-consumable product and handle platform specifics such as pending transactions or past purchases.

Query the store for available products, populate local lists, and persist product data to SharedPreferences and webview if available.

Restore or query past purchases from the store, process Android startup purchases, persist results, and log findings.

Persist product JSON to SharedPreferences and optionally send it to the embedded webview client.

Persist purchase JSON to SharedPreferences, send it to webview, and clear affiliate code state if applicable.

Post payment info to backend and call onSuccess when backend confirms.

Retry any pending purchases that were stored due to missing userId. This should be called whenever a valid userId becomes available.

Check current local subscription status derived from restored purchases.

Public entry to restore purchases (invokes internal restore logic).

Dispose of subscriptions and platform-specific delegates.

Allow continued processing of transactions by default.

Indicate whether price consent UI should be shown; returns false here.

Initialize purchase service (no-op on web)

Update user ID (no-op on web)

Connect to store (no-op on web)

Buy product (not available on web)

Handle post purchase (no-op on web)

Get subscription status (always returns no subscription on web)

Get user membership status (returns not paid on web)

Check if discounts are available (always false on web)

Retry pending purchases (no-op on web)

Restore purchases (no-op on web)

Dispose (no-op on web)

Returns the shared QRService singleton used to manage scanning and scan state.

Get camera permission for QR scanning

Scan QR code using the camera

Dispose resources

Generate an astrological report dynamically based on chart type. This method handles all report types using a single interface. It leverages HoroscopeService for payload building to avoid duplication.

Validate inputs based on chart type requirements

Build chart payload using PayloadService Uses PayloadService public methods to build payload for reports. This ensures consistency with chart calculations throughout the app.

Generate AI report from structured data Use this for reports that don't require chart calculations: - Matrix category reports - Tarot readings (future) - Ritual guidance (future) Backend handles: - Prompt template selection - Constraint validation - AI generation - Response logging for AITrainer

Generate Matrix category report Type-safe wrapper for Matrix reports. Takes a MatrixReportRequest which contains all necessary data and metadata. Example: ```dart final request = MatrixReportRequest( category: 'Path & Career', viewFilter: 'foundation', items: filteredItems, userName: user.name, matrixType: MatrixType.self, ); final result = await reportService.generateMatrixReport(request); ```

Convert to JSON for backend

Normalize UI filter names to backend constants 'foundation' → 'foundation' 'journey' → 'journey' 'all aspects' → 'all'

Get degree information including Sabian symbol Example API call: ``` GET https://astromatrix.org/API/Astrology/GetDegreeInfo ?degree=22 &sign=Sagittarius &type=Transit ```

Get degree info from MatrixItem

Get Sabian symbol image URL (REMOTE - use Image.network)

Get Sabian image URL from DegreeInfo

Get tarot card image URL (REMOTE - use Image.network)

Check if a degree is a critical degree ✅ Uses AstroHelper for modality lookup

Optional method to edit/modify payload before creating URL Override this if you need to transform the payload

Convert payload values to URL-safe string format Handles different data types: - String: URL encoded as-is - int/double: Converted to string - bool: Converted to 'true'/'false' - List: Converted to comma-separated values (for simple lists) - null: Skipped

Build query parameters from payload map Converts payload map to query parameters, URL-encoding each value

Build the share URL with query parameters Returns a URL in the format: https://astromatrix.app/share/{type}?key1=value1&key2=value2 Each value is URL-encoded automatically by Uri

Open the native share sheet with the share URL Optionally provide a subject and text for the share dialog

Get a human-readable preview of what will be shared Override in subclasses to provide meaningful preview text

Generates a new app-specific user ID with format: app-F########## The numeric portion is at least 10 digits for uniqueness

Check if a user ID was generated by the app

Main startup decision method Call this before showing any UI to determine the correct flow

Public check for whether the account has at least one profile (local or server). Use this before redirecting to intro so returning users with profiles go to daily.

Mark intro as completed (synced to server)

Check if intro was already completed

Ensure user ID exists, generating one if needed Returns the user ID (existing or newly generated)

Sync user ID from WebView (called when WebView reports a user ID) Only updates if we don't already have a valid user ID

Get current user ID (does not generate one)

Pass startup user ID to WebView This ensures WebView has the correct user ID for its localStorage

Convert Princess to Page, Prince to Knight Matches convertTarotTitle() in JS

Get tarot card data from API WITH AUTO-FETCHED TRAITS ✅ Matches getTarotCard() in JS ✅ Automatically fetches and includes traits in result ✅ NO CACHING - ComponentService handles caching when called via getItem() Parameters: - [cardImage]: Card key/image (e.g., "The Fool", "A00", etc.) - [deck]: Deck type ("rider waite", "astrotarot", "1" for reversed, null for default) - [reversed]: Whether card is reversed - [theme]: Card theme (optional) - [timeframe]: Timeframe in seconds (default: 60) - [category]: Trait category for API call (e.g., "Tarot", "Tarot Minor Arcana") - [language]: Language code (default: current language)

Get tarot card as ComponentResult (for ComponentService integration) ✅ Called by ComponentService when category is tarot-related ✅ Returns ComponentResult format with traits included ✅ NO CACHING - ComponentService handles caching ✅ Uses user's selected deck from storage

Fetch tarot traits from GetComponentTraits API ✅ Called internally by getTarotCard() ✅ NO CACHING - ComponentService handles caching

Transform flat array API response into grouped structure ✅ FULLY DYNAMIC - automatically handles ANY trait category from API

Open tarot card modal (convenience method) Matches openTarotCard() in JS

Open tarot card from URL link Matches openTarotLink() in JS Parses URL like: /tarot/astrotarot/A00 Extracts card code (A00) and opens with astrotarot deck

Get spread layout array - matches getSpreadBits() in JS Returns array where 0 = empty cell, 1-7 = card position For 3x3 grid spreads, returns 9 elements For linear spreads, returns card count

Get tarot spreads from API Matches getTarotSpreads() in JS Caches results for performance

Get tarot reading from API Matches the GetTarotReading API call in TarotCtrl.js

Get list of cards by section (wands, pentacles, cups, swords, major) Matches getTarotList() in JS [deck] - Optional deck name. If 'rider waite' or 'rider', converts Princess->Page, Prince->Knight For Thoth-style decks (astrotarot, osho), keeps Princess/Prince names

Open tarot card detail screen InputParameters: - [cardName]: Name of the tarot card (e.g., "The Fool") - [context]: BuildContext for navigation For simplicity, this method creates a minimal MatrixItem and navigates to ComponentScreen directly. [category] is derived from the card name.

Clear cached spreads (useful for refresh or logout)

Callback that main.dart will register to rebuild the app

Initialize theme from preferences

Update theme and save to preferences

Launch a URL and navigate to the appropriate screen with parameters. - Resolves share URLs (`/share/{type}?params`) to internal routes - Preserves query parameters for the target screen - Uses [context] if provided, otherwise falls back to [SystemNotifier.navigatorKey] Returns `true` if navigation was performed, `false` if the URL could not be resolved or context was unavailable. Example (from future in-app chat): ```dart onTap: () => UrlNavigationService.launchAndNavigate(context, message.linkUrl); ```

Resolve a URL to an internal route string (path + query) without navigating. - Share URLs → internal route (e.g. `/chartview?u1name=...`) - Direct Flutter routes → normalized URL - Returns `null` if the URL cannot be resolved or is not an app URL Use this for: - Link preview / validation before navigation - Checking if a URL can be opened in-app

Returns `true` if the URL belongs to this app and can be opened in-app. Use this to decide: open in-app vs open in external browser.

Returns `true` if the URL is a share URL (`/share/{type}?params`).

Initialize webview with controller - no-op on web

Set webview settings - no-op on web

Clear webview cache - no-op on web

Setup JavaScript handlers - no-op on web

Send data to webview - no-op on web

Send JSON data to webview - no-op on web

Load URL in webview - no-op on web

Check if webview can go back - always false on web

Go back in webview - no-op on web

Get current URL - always null on web

Dispose resources - no-op on web

Diagnostic Test: Form vs UserProfile Calculation This test uses the SAME birth data and calls it two ways: 1. calculatePositionsForForm() - which gives CORRECT results 2. Save as UserProfile, then calculatePositions() - which gives WRONG results We then compare the payloads and results to find the difference.

Application entry point that initializes platform bindings, services, and runs the app. Summary: - Initializes Flutter bindings, language service, integration splash info, and Firebase. - Applies system UI configuration for Android (edge-to-edge status/navigation bar settings). - Initializes privacy/ads (CMP + ATT + MobileAds) via initPrivacyAndAds(). - Registers Firebase messaging background handler. - Prepares WebViewService and initializes AppNavigation for hybrid routing. - Checks and sends affiliate install information. - Initializes ThemeService for dynamic theme switching. - Finally calls runApp to launch the Flutter UI.

Firebase Cloud Messaging background handler used when messages arrive while the app is terminated or in background. Summary: - Ensures Firebase is initialized in the background isolate and logs the incoming message id.

Initialize privacy and ads using CMP (Consent Management Platform) and iOS ATT flow. Summary: - Initializes Google Mobile Ads SDK and handles user consent flow via UMP (User Messaging Platform). - Requests ATT permission on iOS using AppTrackingTransparency. - Ensures MobileAds is initialized after consent state is resolved.

Request consent information update and show the consent form if required by UMP/ConsentInformation. Summary: - Calls ConsentInformation.instance.requestConsentInfoUpdate with the provided params. - If a consent form is available, tries to load and display it using ConsentForm.loadAndShowConsentFormIfRequired. - Completes when the UMP flow is finished or on timeout.

Request Apple App Tracking Transparency (ATT) permission on iOS. Summary: - Uses AppTrackingTransparency.requestTrackingAuthorization to ask for user consent to track across apps/websites for advertising.

Initialize Google Mobile Ads after user consent state is known. Summary: - Checks UMP's canRequestAds state and initializes MobileAds.instance if advertising is permitted. - If canRequestAds is false, attempts a fallback initialization for testing or degraded flows.

Determines the first widget to show based on startup checks. This prevents the "double-loading" flicker on web.

WEB ENTRY POINT - Complete web-safe initialization All services have been stubbed and are web-compatible. This entry point initializes only web-safe services.

Determines the first widget to show based on startup checks.

Register Flutter routes for the web app using the same mapping as the mobile app's new-UI HybridRouter registration in main.dart.

Compute the initial route for the web app based on the current browser URL. Order of resolution: 1. If no meaningful path/query → return '/' (fallback). 2. If path is a registered Flutter route → use path + query. 3. Else try HybridRouter.tryResolveIntelligentRoute (component/share/tarot). 4. If still unresolved → return '/' (fallback).

WEB ENTRY POINT - Complete web-safe initialization All services have been stubbed and are web-compatible. This entry point initializes only web-safe services.

Determines the first widget to show based on startup checks.

Register Flutter routes for the web app using the same mapping as the mobile app's new-UI HybridRouter registration in main.dart.

Compute the initial route for the web app based on the current browser URL. Order of resolution: 1. If no meaningful path/query → return '/' (fallback). 2. If path is a registered Flutter route → use path + query. 3. Else try HybridRouter.tryResolveIntelligentRoute (component/share/tarot). 4. If still unresolved → return '/' (fallback).

Returns the shared QRService singleton used to manage scanning and scan state.

Get camera permission for QR scanning

Scan QR code using the camera

Dispose resources

Creates an [AppLayoutBase].

Builds the responsive banner area with optional background image, gradient overlay, and centered title/subtitle.

Creates a CompactLayout with a banner (image/gradient/title) and a scrollable content section.

Get current route path from ModalRoute