@robono/location-react-native 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+Optional map screens, avatar pins, location cards, geofence editor and Expo foreground/background location adapters. Accuracy refinement and opt-in accelerometer/gyroscope classification; raw sensor samples stay on the device.

package/LICENSE

@@ -0,0 +1,130 @@
+ROBONO SDK LICENSE AGREEMENT
+Version 1.0, July 20, 2026
+
+Copyright (c) 2026 Add to Loop LLC. All rights reserved.
+
+This Robono SDK License Agreement (the "Agreement") is between Add to Loop LLC,
+operating the Robono service ("Robono"), and the person or entity that downloads,
+installs, copies, or uses the Software ("You"). By downloading, installing,
+copying, or using the Software, You accept this Agreement. If You do not accept
+it, do not use the Software.
+
+1. Definitions
+
+"Software" means this Robono software development kit, its documentation, and
+any updates Robono provides under this Agreement.
+
+"Robono Service" means the messaging interoperability, routing, policy,
+conversion, delivery, and related services operated or expressly authorized by
+Robono.
+
+"Application" means a product or service owned or controlled by You that is
+authorized to connect to the Robono Service.
+
+2. Limited License
+
+Subject to this Agreement, Robono grants You a limited, non-exclusive,
+non-transferable, non-sublicensable, revocable license to:
+
+(a) install, copy, and use the Software internally to develop, test, and
+operate an Application that communicates with the Robono Service; and
+
+(b) reproduce and distribute the portions of the Software that are necessarily
+included in Your Application, solely in compiled, minified, bundled, or object
+code form and solely as needed for that Application to communicate with the
+Robono Service.
+
+No right is granted to distribute the Software as a standalone product or SDK.
+
+3. Restrictions
+
+You may not, and may not permit another person to:
+
+(a) sell, rent, lease, sublicense, publish, or redistribute the Software as a
+standalone product, library, SDK, or service;
+
+(b) use the Software or a modified or derivative version of it to develop,
+provide, or support a product or service that competes with the Robono Service;
+
+(c) use the Software to bypass Robono, avoid applicable usage controls or fees,
+or access the Robono Service without authorization;
+
+(d) remove or alter copyright, trademark, attribution, or proprietary notices;
+
+(e) reverse engineer, decompile, or disassemble the Software except to the
+limited extent applicable law expressly prohibits this restriction; or
+
+(f) use the Software in violation of applicable law, the rights of another
+person, or the terms governing access to the Robono Service.
+
+4. Ownership and Reserved Rights
+
+The Software is licensed, not sold. Robono and its licensors retain all right,
+title, and interest in the Software and all related intellectual property.
+Except for the limited rights expressly granted in Section 2, all rights are
+reserved.
+
+No patent license is granted except the minimum license, if any, necessarily
+required to exercise the rights expressly granted in Section 2, and that
+limited patent license applies only while the Software is used with an
+authorized Robono Service.
+
+5. Service Access
+
+This Agreement does not itself grant an account, API credentials, service
+availability, support, or a right to access the Robono Service. Service access
+may be governed by additional terms, plans, limits, and policies. Robono may
+suspend or terminate access to protect users, systems, legal compliance, or the
+integrity of the Robono Service.
+
+6. Updates and Support
+
+Robono is not required to provide maintenance, updates, support, or continued
+availability of any version of the Software unless separately agreed in
+writing.
+
+7. Term and Termination
+
+This Agreement continues until terminated. Your rights terminate automatically
+if You breach this Agreement. On termination, You must stop using the Software
+and delete copies under Your control, except for copies necessarily contained
+in previously distributed Applications. Sections 3, 4, 8, 9, 10, and 11
+survive termination.
+
+8. Disclaimer of Warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS" AND
+"AS AVAILABLE," WITHOUT WARRANTIES OF ANY KIND, EXPRESS, IMPLIED, OR
+STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+9. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, ROBONO WILL NOT BE LIABLE FOR INDIRECT,
+INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS
+OF DATA, REVENUE, PROFITS, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING FROM OR
+RELATING TO THE SOFTWARE. ROBONO'S TOTAL LIABILITY RELATING TO THE SOFTWARE
+WILL NOT EXCEED THE GREATER OF ONE HUNDRED U.S. DOLLARS (US $100) OR THE AMOUNT
+YOU PAID ROBONO FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE THE EVENT
+GIVING RISE TO THE CLAIM. THESE LIMITATIONS APPLY TO THE MAXIMUM EXTENT
+PERMITTED BY LAW.
+
+10. Governing Law
+
+This Agreement is governed by the laws of the State of Florida, excluding its
+conflict-of-laws rules. The state and federal courts located in Palm Beach
+County, Florida have exclusive jurisdiction, and each party consents to their
+jurisdiction and venue.
+
+11. General
+
+You may not assign this Agreement without Robono's prior written consent.
+Robono may assign this Agreement in connection with a reorganization, transfer
+of intellectual property, financing, merger, acquisition, or sale of all or
+substantially all of the relevant assets. If a provision is unenforceable, it
+will be enforced to the maximum extent permitted and the remaining provisions
+will remain effective. A waiver must be in writing. This Agreement is the
+entire agreement concerning the Software unless You and Robono sign a separate
+written agreement that expressly replaces it.
+
+Questions about this license may be submitted at https://robono.com/contact.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# Optional Robono mobile Maps
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The supplied map controls use Robono’s shared SVG icons. Install `react-native-svg` with your framework’s native dependency installer.
+
+Use these components together or individually. Your app owns navigation, authentication, consent and permission policy. Maps can be a standalone screen, part of messaging, or both.
+
+Exports:
+- `LocationScreen`: sharing controls, freshness, speed, heading, duration and stop control.
+- `LocationMessage`: a location card for your chat UI.
+- `GeofenceEditor`: controlled circle/polygon drawing, arrival/departure toggles and validated saving.
+- `AvatarLocationMap`: avatar pins with tap-to-open name/update details, a Directions action and a destination route. Tapping the map closes the details without removing the avatar.
+- `RobonoMapView`: Google map, markers, circles, polygons and routes.
+- `@robono/location-react-native/expo`: foreground/background GPS adapters.
+- `@robono/location-react-native/motion`: opt-in movement sharing with durable stop recovery.
+- `@robono/location-react-native/app.plugin.cjs`: Expo native configuration.
+
+Register your bundle ID and Android package/signing certificate with Robono. Activate access in Maps → Add Maps to your app, then download each platform’s app configuration. Robono provides map access restricted to those identifiers. Keep that managed build configuration in your private build environment. Do not ask end users for keys.
+
+```js
+plugins: [['@robono/location-react-native/app.plugin.cjs', {
+  accessFiles: {ios: './robono-maps-ios.json', android: './robono-maps-android.json'},
+  background: true,
+  permissionText: 'Share your location with the people you choose.',
+}]]
+```
+
+Native map/location dependencies require a native build. Match Expo dependencies to the host's supported Expo version and commit its lockfile. These peers are optional at the product level: apps not using Maps do not install this package.
+
+## Start only after the user chooses to share
+
+```ts
+import {defineLocationTask, createExpoLocationSharing} from '@robono/location-react-native/expo';
+
+// Module scope, including on a background launch:
+defineLocationTask({taskName: 'app-location-sharing', store: trackingStore,
+  getClient: restoreAuthenticatedLocationClient, createId, onError: handleTrackingError});
+
+const sharing = createExpoLocationSharing({client, createId,
+  taskName: 'app-location-sharing', store: trackingStore,
+  notificationTitle: 'Location sharing is active',
+  notificationBody: 'Open the app to stop sharing.',
+});
+await sharing.start({grantId, mode: 'live', durationMinutes: 60,
+  intervalSeconds: settings.updateIntervalSeconds, background: true});
+await sharing.stop();
+```
+
+`trackingStore` implements async `load()` and `save(context|null)` using the app's persistent storage. It stores only session ID, expiry and update interval. Authentication is restored separately using the app's secure session storage. Never persist a network API key there. Register the task once, outside React render functions.
+
+Android requires an ongoing foreground-service notification for background sharing. iPhone requires background location permission and displays its location indicators. Ask for background access only for a user-selected feature. The OS may delay updates or stop tracking when the app is force-closed; show stale data as last known. On sign-out, call `stop()` before discarding authentication. If offline, stop local GPS immediately and retry the server stop once connected; the share also expires on the server.
+
+Use `observeLocation` from the core client for viewers. Clear old positions when its view becomes null. `dispose()` releases foreground watchers; it deliberately does not stop a separately requested background share. Stop background sharing explicitly with `stop()`.
+
+Do not treat an ordinary contact relationship as permission to track someone. The backend must establish directed, time-bounded grants and synchronize revocation.
+
+## Chat map
+
+```tsx
+<AvatarLocationMap position={view.position} name={view.name}
+  avatar={view.avatar} updated={locationAge(view.position.capturedAt)}
+  route={view.route?.coordinates} destination={view.destination}
+  onDirections={openExternalDirections}
+  onLocateMe={getForegroundPosition} />
+```
+
+Import `getForegroundPosition` from `@robono/location-react-native/expo` for the optional Locate Me control. It requests foreground access only when pressed, uses the viewer position locally, and cancels pending GPS work when the map closes. It does not share that position with the other participant. The friend control zooms to the shared pin; Locate Me fits both positions within the visible map. The map includes Regular and Satellite views. Dragging keeps the details open; tapping elsewhere dismisses them.
+
+The containing screen controls navigation and clears the map when access expires or is withdrawn. `onDirections` should open Apple Maps directly on iPhone or Google Maps directly on Android. Render `tripSummary(view, units)` beside a live trip for speed and estimated arrival; do not present stale estimates as current.
+
+For an atomic chat start, pass `startWithPosition` to `createExpoLocationSharing`. It receives the user's first accurate fix and a request ID before background GPS starts. Forward those to `LocationChatClient.start`; the adapter skips the redundant first update. Persist a start-recovery record before sending the request, so your app can recover a lost response or interrupted start. Store only session/recovery metadata, never a history of coordinates.
+
+Permission recovery: the Expo adapter throws `LocationPermissionError` with `permission` (`foreground` or `background`) and `canAskAgain`. Offer a settings link if access is denied; do not silently downgrade a background share. A host can offer an explicit open-app-only trip using `background: false`, keep the sharing controller alive after its sheet closes, and call `stop()` when the app enters the background. Robono Messenger supplies this recovery flow.
+
+## Improve accuracy
+
+Call `getPrecisePosition({signal, onPosition})` from the Expo entry point only after
+the user selects **Improve accuracy**. It reports usable fixes while refining for
+up to 12 seconds and returns the best recent reported radius. Pass the resulting
+position to your map and display `locationAccuracyLabel(position)` from the core
+package. Additional decimal places do not mean additional accuracy. This does
+not promise an exact position or upload Wi-Fi/Bluetooth scans.
+
+## Share device movement
+
+Install the `expo-sensors` version compatible with your Expo SDK and enable
+`motion: true` in the Robono location plugin. Use an account-specific persistent
+store implementing `load()` and `save(value|null)` for pending stop recovery.
+
+```ts
+import {createExpoMovementSharing} from '@robono/location-react-native/motion';
+const movement = createExpoMovementSharing({
+  client, store: movementStore, createId, onError: showMovementError,
+});
+await movement.recover(); // On signed-in startup: finish a pending stop.
+// Wire these to the optional LocationScreen onMotionSharing control:
+await movement.start(sessionId); // Only after the user chooses Share movement.
+await movement.stop();
+```
+
+Keep one controller per signed-in account. Call `stop()` when sharing ends or
+before signing out. It stops sensors immediately, even without a network, and
+retains a failed server-stop request for the next authenticated startup. A restart
+never automatically resumes movement capture. Do not reuse another account's store.
+
+Pass `view.motion` to `LocationScreen` for the viewer. Readings distinguish still,
+slight movement and moving; stale readings display unavailable. Raw sensor samples
+stay on the phone. Capture runs while the app is open on both platforms and pauses
+in the background. These indicators cannot establish whether someone is touching
+the screen, reading, or using another app.
+
+`GeofenceEditor` offers entry/exit alerts, arm-on-entry, and optional schedules
+with days, local time zone, and expected arrival/departure times. A missing or
+inaccurate position produces **location unavailable**, not a claim that the person
+is outside. Schedule times apply to the chosen time zone, including daylight saving.