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.

Fetch extended moon information including phases, next events, and detailed reports. Summary: Retrieves comprehensive moon-related data including VOC, OOB, and next moon phases.

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.

Translates text from one language to another using Google's free 'gtx' endpoint. [text] The content to translate. [targetLanguage] The ISO-639-1 code for the target language (e.g., 'es', 'fr'). [isHtml] Placeholder for consistency; gtx automatically tries to preserve common tags.

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

Helper functions for compute()

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

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

Deletes the oldest records in a namespace based on created_at timestamp

Returns the singleton instance of [LanguageService].

Checks if a specific string is currently being translated by GPT in the background.

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.

Loads GPT fallback translations from disk into [_gptTranslationCache]. In-memory entries win over disk for the same key (session overrides).

Persists the full GPT map for [language] so it survives app restarts.

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.

Skips translation only for explicit user skip list, **emails**, and **date-like** strings. Everything else can use the remote table or GPT. Previously also skipped URLs, phones, numbers, Title Case words, etc.; that logic is commented near [_skipDatePatterns] for later reuse.

GPT cache updated; rebuild widgets that listen to [LanguageService].

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.

Looks up [name] in the remote language table, then GPT cache; if missing, queues a **debounced batch** GPT translation and returns [name] until ready. When GPT completes, [notifyListeners] runs so UI rebuilds. The synchronous part does not await the network; GPT runs in the background. [type] is reserved for future use.

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 a fast batch of individual Google Translate calls (for fallbacks).

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.

Performs an isolated Google Translate call for large/HTML items.

Ultimate fallback to GPT for a specific string.

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)

Device-level or UI preference: always writes [StorageService]; when logged in, merges into the profile prefs record (same as [setPreferenceLanguage]).

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.

Removes a previously registered `message_received` callback.

Disconnects the socket and releases network resources.

Sets the in-house ad percentage for current session only.

Returns true if an in-house ad should be shown based on the rotation percentage. Always returns true on Web (no AdMob support). Always returns false if ads are disabled (user subscribed).

Factory constructor returning the singleton AdsService instance.

Returns how many pages should pass between interstitial ads for the given session count. Returns 0 if no tier applies (session count below all thresholds → no page-based ads).

Called on each eligible page navigation. Returns true when the page threshold is reached and an interstitial should be shown; resets the counter when it fires.

Updates the minimum interval between interstitial ads (legacy setter, kept for compatibility).

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

Syncs ad configuration from the backend (intervals, reward toggles, session tiers).

Refreshes ad status based on comprehensive subscription info. Returns whether the user is paid; `false` on error (ads state unchanged except via [setAdsEnabled] failure paths).

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 Returns true if an ad was successfully loaded and show was triggered.

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

Records an ad being successfully shown. Labeled by adType ('interstitial', 'rewarded_interstitial', etc.). Increments local/DB user session statistics under the 'ads_seen' key.

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)

Emits the app-version metric at most once per install per build. Safe to call on every startup — it is a no-op if the current build was already reported on this device. Failures are swallowed so startup is never blocked by metrics. The counter re-fires on every version OR build bump, so each distinct release on a device is counted exactly once.

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

Single source of truth mapping layer that selects the correct category based on chart type, data context (itemType) and section. Moved from ChartScreen to ChartService to break the circular import between chart_screen.dart ↔ chart_widgets.dart which caused null-dereference crashes on web.

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 } Single-wheel charts compare one set of bodies against itself, so the aspect grid is symmetric (planet vs the same planet set on both axes). Two-wheel charts (transit, synastry, composite, progressed, returns, relocation, draconic) compare two distinct sets: rows = natal bodies, columns = transit/comparison bodies. For those the grid must NOT be mirrored, otherwise both axes read as the same set.

Get aspect grid for the main transit table using mainAspectRowIndices. Rows: Sun–Pluto, North Node, South Node, Ascendant, Midheaven (14 rows) Columns: Sun–Pluto (10 columns)

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. Respects showPlanet toggle — disabled bodies are excluded from 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

Parse hex color string (#RRGGBB) or rgba string (rgba(r,g,b,a)) to Color

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

Synchronous parse -- used on web where isolates aren't available. Input format: [[name, country, lat, lng, pop_thousands], ...]

Top-level function for compute() on native platforms.

Open component view - handles everything Central method for opening component screen from anywhere in the app. Creates MatrixItem and navigates to ComponentScreen. If you have a full MatrixItem with dates/metadata, pass it via [matrixItem]. Otherwise, a minimal MatrixItem will be created from [componentName] and [category]. For transit components, this will attempt to look up the full data from cache. Example: ```dart ComponentService.openComponentView( context, componentName: 'Sun', category: 'Zodiac Planets', ); ```

Navigate to ComponentScreen with the given MatrixItem

Find a transit item in the horoscope cache by component name and category

Find a matrix item in the current (main) user's horoscope cache by component name, searching across ALL categories. This is the "look the notification title up in the calculateHoroscopes result" lookup used by notification routing: the title is the source of truth and the matched item's `facet`/`category` drive the destination. Returns null when the title isn't present in the computed matrix for the current user (caller treats that as `notification_item_not_found`).

Find a forecast item (moon phases, lunations, events, etc.) by name across the given [types], using the SAME `ForecastService.fetchForecastData` lists the moon/calendar screens render and tap. The returned [MatrixItem] carries the correct `eventId` and `Category` (e.g. "Forecasts") so ComponentSummary loads the right component — a minimal item would send `Id=undefined` and the wrong category.

Find a Void-of-Course or Out-of-Bounds event by notification title and build the same MatrixItem the moon screen taps open (VOC → "Void of Course", OOB → "Transit Out of Bounds"). Keyword-gated so it only runs for actual VOC/OOB notifications.

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), ), ); ```

Clear both in-memory and disk caches

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

Open component view - handles everything Central method for opening component screen from anywhere in the app. Creates MatrixItem and navigates to ComponentScreen. If you have a full MatrixItem with dates/metadata, pass it via [matrixItem]. Otherwise, a minimal MatrixItem will be created from [componentName] and [category]. For transit components, this will attempt to look up the full data from cache. Example: ```dart ComponentService.openComponentView( context, componentName: 'Sun', category: 'Zodiac Planets', ); ```

Navigate to ComponentScreen with the given MatrixItem

Find a transit item in the horoscope cache by component name and category

Find a matrix item in the current (main) user's horoscope cache by component name, searching across ALL categories. This is the "look the notification title up in the calculateHoroscopes result" lookup used by notification routing: the title is the source of truth and the matched item's `facet`/`category` drive the destination. Returns null when the title isn't present in the computed matrix for the current user (caller treats that as `notification_item_not_found`).

Find a forecast item (moon phases, lunations, events, etc.) by name across the given [types], using the SAME `ForecastService.fetchForecastData` lists the moon/calendar screens render and tap. The returned [MatrixItem] carries the correct `eventId` and `Category` (e.g. "Forecasts") so ComponentSummary loads the right component — a minimal item would send `Id=undefined` and the wrong category.

Find a Void-of-Course or Out-of-Bounds event by notification title and build the same MatrixItem the moon screen taps open (VOC → "Void of Course", OOB → "Transit Out of Bounds"). Keyword-gated so it only runs for actual VOC/OOB notifications.

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), ), ); ```

Clear both in-memory and disk caches

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). Resets view counter and gated state so each session starts fresh.

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. Results are cached for [_paidStatusCacheDuration] to avoid hammering the IAP + backend on every save attempt.

Refresh paid status (useful after login or purchase). Always busts the cache and re-fetches from IAP + backend.

Fetch the live saved-entry count from the server. Uses `GET NODE_URL/journals/count?uid=<profileId>&category=<category>`. Falls back to the locally-cached count on any network error so the app continues to work offline.

Check the free-tier saved-charts limit against the **server** count. Returns `true` if the limit has been reached → caller should block the save and show the upgrade modal. Returns `false` when the save is allowed. Paid users always get `false` (no limit).

Check the free-tier saved-reports limit against the **server** count. Returns `true` if the limit has been reached → caller should block the save and show the upgrade modal. Returns `false` when the save is allowed. Paid users always get `false` (no limit).

Reset all gating state (for testing or user request)

Get debug info for logging

Tab 1 – Moon Sign Changes: horoscopeType == 'MoonPhase' only. These are the frequent (every 2-3 day) sign transitions; no phrase.

Tab 2 – Lunations: New Moon & Full Moon only (horoscopeType == 'MOON'). These have inspirational phrases and happen ~twice per month.

Hash contains `short` (or component matches short-tier planets).

Hash contains `long`, or (when hash missing) not a short-tier forecast.

Collapsed Long Term calendar: yearly (current year), active outer-planet sign ingresses, and the next monthly horoscope.

Expanded Long Term calendar: all relevant rows, yearly pinned first then by begins.

Soonest [MatrixItem.ends] first; rows without an end date go last.

Legacy HoroscopeService horoscopeFilter: Name == "Retrograde".

Legacy EventsCtrl RetrogradeList: ongoing retrogrades (TimeAway contains "Ends").

Legacy Calendars Retrograde tab: Name == Retrograde, full current-year list.

Load from local [StorageService] first (guest-safe), then optional profile prefs.

**Auto-saves** on every change (slider [onChanged]). No separate Apply button. Works for guests (local only) and signed-in users (local + merged profile prefs).

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().

Clears temporary preference override used by test or scoped views.

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

Restore user1 ID from local storage first, then PreferenceService. Critical for web refresh to preserve last selected user.

Restore user2 ID from local storage first, then PreferenceService.

Persist user1 ID to preferences and local storage.

Persist user2 ID to preferences and local storage.

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

Resets user1 to the main user (profileID). Called on cold start and every time the app resumes from background. Falls back to the existing user if no main user is found.

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.

Get the effective timezone offset in minutes. 1. If a location is set in currentLocation → use that location's timeOffset 2. If no location is set → fallback to the device's system timezone

Set primary user for calculations. [persist]: when false, only memory is updated (e.g. shared chart deep link in [ChartScreen]); saved `chart_service_user1_id` is unchanged.

Set secondary user for relationship calculations. [persist]: when false, only memory is updated (shared chart / ephemeral UI).

Reload user1/user2 from saved preference IDs into memory only. Used after an ephemeral share session (prefs were never updated with the synthetic `shared_u1_*` id). If the saved user1 id is missing or stale, falls back to [_loadDefaultUser].

Replace chart users in memory only (no writes to user id preferences). Used when exiting or pausing an ephemeral shared-chart session from a synchronous route callback.

Starts an ephemeral session if one isn't already active, snapshotting the real user profiles first.

Restores the real profiles from snapshot (or preferences) if active, and resets ephemeral state.

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

Checks if the transit date is "stale" (hasn't been refreshed in 2+ hours). If stale, resets the viewed context to 'now' and returns true. This is typically called when the app resumes from the background.

Clear secondary user.

Clear both users (useful for logout scenarios).

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.

Warm the positions cache for a set of transit dates in the background. This does NOT change the current [_transitDate] or emit any stream events — it only populates the memory/disk caches so that subsequent forward/back navigation to those dates resolves instantly from cache instead of hitting the network. Runs sequentially, skips dates already cached, and silently swallows errors (prefetch is best-effort). Re-entrant calls are ignored while a prefetch batch is already running.

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.

Synchronously find a planet from the in-memory POSITIONS cache (calcPositions). Companion to [getPlanetSync], which reads the horoscope cache. Some screens (e.g. the chart screen) populate the positions cache but not the horoscope cache, so callers that need a planet's current sign/degree regardless of which screen loaded the data should try both. The positions payload is stored under `positions_<self|relationship>_...` (NOT `positions_transit`) and contains two arrays: `planets` (natal) and `transitPlanets` (current transit). For a transit lookup we read `transitPlanets`; for a birth lookup we read `planets`. Returns null when no positions payload is loaded or the planet isn't present.

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 extended moon information from the dedicated API.

Get moon phase information using the dedicated Moon Phase API. Results are cached until app restart.

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 active in-house ad. All active ads from every tag (ItemContent, Link, Tarot, Promo, etc.) are pooled together so every ad gets equal random exposure. The [type] parameter is accepted for API compatibility but is ignored — use [getPromoText], [getItemContentAd], or [getTarotAd] for targeted pulls. Returns null if user is subscribed (paid) or no ads are loaded yet.

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 the first active promo text string. Returns null if user is subscribed (paid).

Returns ALL active in-house ads as a list (used for purchases/list views). The [type] parameter is kept for compatibility but all active ads are returned. 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)

Check if location service is enabled

Check and request location permissions

Get current GPS coordinates without needing a web controller

Get current GPS coordinates (legacy version with web controller evaluation)

Complete location flow: check service, permissions, get location

Get current GPS position (just coordinates, no WebView). Returns null if permission is denied; throws [PermissionDeniedException] so callers can show a browser-settings message instead of a generic error.

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

Maps ChangePassword API JSON (`success`, `message`, `data`) to [ApiResult].

Maps ChangePassword API JSON (`success`, `message`, `data`) to [ApiResult].

Maps ChangePassword API JSON (`success`, `message`, `data`) to [ApiResult].

Maps ChangePassword API JSON (`success`, `message`, `data`) to [ApiResult].

Setup data for a native report

Generate HTML report for matrix items (public method)

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

Initializes the socket connection and sets up the badge increment listener. Called when the user enters the support/messages screen.

Checks for unread messages on startup and sets the badge count. Lightweight REST call — no socket connection needed.

Disposes the socket connection when the user exits the support screen.

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

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

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 app_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 webview controller reference (call when the webview is recreated).

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.

Puts the completed purchase into [_purchaseProducts] so [purchaseProducts] listeners (Store / Account subscription UI) refresh immediately. Previously only prefs/WebView were updated; the in-memory list stayed empty until the next full restore, so UI never reacted to [purchaseProducts].

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.

Clear the persisted processed-purchase-ID set. Call this before restoring so every past purchase is re-synced with the backend.

Public entry to restore purchases. Clears the processed-ID cache first so every past purchase is re-verified against the backend DB — this recovers "paid but no record" cases automatically.

Dispose of subscriptions and platform-specific delegates.

Returns current user email (already available via _userId in mobile)

Web-only: Open Stripe billing portal

Web-only: Process Stripe checkout session

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)

Fetch Stripe products from Node.js backend

Update user ID (no-op on web)

Update webview controller (no-op on web)

Connect to store (no-op on web)

Buy product (Stripe redirect for web)

Open Billing Portal for subscription management

Handle post purchase (no-op on web)

Get subscription status from backend

Get user membership status (returns paid status from backend)

Check if discounts are available (always false on web)

Retry pending purchases (no-op on web)

Clear processed purchase IDs (no-op on web)

Restore purchases (no-op on web)

Dispose (no-op on web)

Helper to get current user identifier (email) 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