@movexgeo/react-native-movex 0.1.0

package/src/types.ts

@@ -0,0 +1,149 @@
+// Public type definitions for the React Native bridge. Mirror the
+// Kotlin (`sdk/android/`) and Swift (`sdk/ios/`) types so cross-
+// platform docs share most of their content.
+
+/**
+ * Per-surface base URLs, or a named preset resolved by the native SDK.
+ *
+ * ## Preset form (recommended)
+ *
+ * Pass `{ preset: 'production' }` to use the native SDK's built-in
+ * production endpoint configuration (`https://movex.citymall.live`).
+ * The URL constants live in the native SDK — TypeScript is intentionally
+ * not the source of truth.
+ *
+ *   `'production'` — `https://movex.citymall.live`, pinning disabled
+ *                    until real SPKI hashes are computed post-deploy.
+ *   `'localDev'`   — emulator/simulator loopback defaults
+ *                    (Android: `http://10.0.2.2:809*`,
+ *                     iOS: `http://localhost:809*`).
+ *
+ * ## Explicit form
+ *
+ * Omit `preset` and supply individual URL strings. All three fields
+ * default to the loopback when absent.
+ *
+ *   `{ ingest: 'https://…', auth: 'https://…', events: 'https://…' }`
+ *
+ * ## Mixed form
+ *
+ * Combine `preset` with explicit overrides — the explicit values win.
+ * Useful for e.g. pointing `events` at a staging service while keeping
+ * everything else on production:
+ *
+ *   `{ preset: 'production', events: 'https://staging.events.example' }`
+ *
+ * ## Cert pinning
+ *
+ * `pinnedHosts` maps an HTTPS hostname to a list of `sha256/<base64>`
+ * SubjectPublicKeyInfo pins. When non-empty, every TLS handshake
+ * against a pinned host is checked before the request body is sent.
+ * See the native SDK docs for the openssl recipe used to compute pins.
+ */
+export interface Endpoints {
+  /**
+   * Named endpoint preset resolved by the native SDK. When set, the
+   * bridge calls the corresponding native factory method
+   * (`Endpoints.production()` / `Endpoints()`) instead of constructing
+   * an `Endpoints` object from explicit URLs. Explicit URL fields and
+   * `pinnedHosts`, when also present, override the preset values.
+   */
+  preset?: 'production' | 'localDev';
+  ingest?: string;
+  auth?: string;
+  events?: string;
+  pinnedHosts?: { [host: string]: string[] };
+}
+
+/**
+ * Battery / accuracy preset. Matches the native SDKs.
+ *
+ *   efficient   - low power, sig-changes only (~500m granularity, runs
+ *                 in background once Always is granted)
+ *   responsive  - balanced, ~50m updates while foreground; sig-changes
+ *                 in background. Default for most apps.
+ *   continuous  - HIGH accuracy, foreground-only unless host app has
+ *                 active foreground location entitlement / Live Activity.
+ */
+export type Preset = 'efficient' | 'responsive' | 'continuous';
+
+export interface ProjectInfo {
+  project_id: string;
+  org_id: string;
+  /** 'paid' | 'shared' | 'local' */
+  tier: 'paid' | 'shared' | 'local';
+  key_type: string;
+  scopes: string[];
+  rate_limit_per_min?: number;
+  features?: string[];
+  data_region?: string;
+}
+
+/**
+ * A single on-device location fix. Delivered via `MovexGeo.onLocations`
+ * for all tier types. For LOCAL-tier projects this is the **only** way
+ * to receive location data — no server traffic is produced.
+ *
+ * Cross-platform shape shared by Android, iOS, and the RN bridge.
+ */
+export interface LocationFix {
+  lat: number;
+  lng: number;
+  /** Horizontal accuracy radius in metres. */
+  accuracy_m: number;
+  /** RFC3339 / ISO-8601 UTC timestamp of the fix. */
+  ts_event: string;
+  /** Ground speed in m/s. Absent when the OS did not report speed. */
+  speed_mps?: number;
+  /** Bearing in degrees [0, 360). Absent when unavailable. */
+  heading_deg?: number;
+  /** Provider / fused source identifier: 'gps' | 'fused' | 'replay'. */
+  source: string;
+}
+
+export interface NearbyFence {
+  id: string;
+  lat: number;
+  lng: number;
+  radius_m: number;
+}
+
+export interface TrackResponse {
+  accepted: boolean;
+  nearby_fences?: NearbyFence[];
+}
+
+/**
+ * Event row matching the geofence + trip union the events-api returns.
+ * `event_type` discriminates: `user.entered_geofence`,
+ * `user.exited_geofence`, `trip.started`, `trip.approaching`,
+ * `trip.arrived`, `trip.completed`, `trip.cancelled`, `trip.expired`.
+ */
+export interface MovexGeoEvent {
+  event_id: string;
+  event_type: string;
+  project_id: string;
+  device_id?: string;
+  user_external_id?: string;
+  geofence_id?: string;
+  lat?: number;
+  lng?: number;
+  accuracy_m?: number;
+  confidence?: number;
+  trip_id?: string;
+  mode?: string;
+  status?: string;
+  ts_event: string;
+  ts_received: string;
+}
+
+/**
+ * Errors raised by the bridge. The `code` field is the same
+ * vocabulary the backend uses (`invalid_key`, `key_revoked`,
+ * `project_suspended`, `bad_request`, etc.). Use it for branchy
+ * error handling rather than string-matching `message`.
+ */
+export interface MovexGeoErrorPayload {
+  code: string;
+  message: string;
+}