Location command (nodes)

संक्षेप में

  • location.get एक node command है (node.invoke के माध्यम से)।
  • डिफ़ॉल्ट रूप से off।
  • Settings एक selector का उपयोग करते हैं: Off / While Using / Always।
  • अलग toggle: Precise Location।

Selector क्यों (केवल switch नहीं)

OS permissions multi-level हैं। हम in-app में एक selector expose कर सकते हैं, लेकिन OS अभी भी वास्तविक grant तय करता है।

  • iOS/macOS: user system prompts/Settings में While Using या Always चुन सकता है। App upgrade request कर सकता है, लेकिन OS को Settings की आवश्यकता हो सकती है।
  • Android: background location एक अलग permission है; Android 10+ पर इसे अक्सर Settings flow की आवश्यकता होती है।
  • Precise location एक अलग grant है (iOS 14+ "Precise", Android "fine" बनाम "coarse")।

UI में selector हमारे requested mode को चलाता है; वास्तविक grant OS settings में रहता है।

Settings model

प्रति node device:

  • location.enabledMode: off | whileUsing | always
  • location.preciseEnabled: bool

UI व्यवहार:

  • whileUsing select करने पर foreground permission request करता है।
  • always select करने पर पहले whileUsing ensure करता है, फिर background request करता है (या user को Settings में भेजता है यदि आवश्यक हो)।
  • यदि OS requested level deny करता है, तो highest granted level पर revert करें और status दिखाएं।

Permissions mapping (node.permissions)

वैकल्पिक। macOS node location को permissions map के माध्यम से report करता है; iOS/Android इसे omit कर सकते हैं।

Command: location.get

node.invoke के माध्यम से called।

Params (suggested):

json
{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}

Response payload:

json
{
  "lat": 48.20849,
  "lon": 16.37208,
  "accuracyMeters": 12.5,
  "altitudeMeters": 182.0,
  "speedMps": 0.0,
  "headingDeg": 270.0,
  "timestamp": "2026-01-03T12:34:56.000Z",
  "isPrecise": true,
  "source": "gps|wifi|cell|unknown"
}

Errors (stable codes):

  • LOCATION_DISABLED: selector off है।
  • LOCATION_PERMISSION_REQUIRED: requested mode के लिए permission missing।
  • LOCATION_BACKGROUND_UNAVAILABLE: app backgrounded है लेकिन केवल While Using allowed है।
  • LOCATION_TIMEOUT: समय में कोई fix नहीं।
  • LOCATION_UNAVAILABLE: system failure / कोई providers नहीं।

Background व्यवहार (भविष्य)

लक्ष्य: model location request कर सके तब भी जब node backgrounded हो, लेकिन केवल तब जब:

  • User ने Always select किया हो।
  • OS ने background location grant किया हो।
  • App को location के लिए background में चलने की अनुमति हो (iOS background mode / Android foreground service या विशेष अनुमति)।

Push-triggered flow (भविष्य):

  1. Gateway node को एक push भेजता है (silent push या FCM data)।
  2. Node संक्षेप में जागता है और device से location request करता है।
  3. Node payload को Gateway को forward करता है।

नोट्स:

  • iOS: Always permission + background location mode आवश्यक। Silent push throttled हो सकता है; intermittent failures की अपेक्षा करें।
  • Android: background location के लिए foreground service की आवश्यकता हो सकती है; अन्यथा, denial की अपेक्षा करें।

Model/tooling integration

  • Tool surface: nodes tool location_get action जोड़ता है (node आवश्यक)।
  • CLI: mayros nodes location get --node <id>।
  • Agent guidelines: केवल तभी call करें जब user ने location enabled किया हो और scope को समझता हो।

UX copy (suggested)

  • Off: "Location sharing is disabled."
  • While Using: "Only when Mayros is open."
  • Always: "Allow background location. Requires system permission."
  • Precise: "Use precise GPS location. Toggle off to share approximate location."