spotny-sdk 0.2.0

package/src/index.tsx

@@ -0,0 +1,141 @@
+import { NativeEventEmitter, NativeModules } from 'react-native';
+import NativeSpotnySdk from './NativeSpotnySdk';
+
+// ── Event names ──────────────────────────────────────────────────────────────
+export const SpotnyEvents = {
+  ON_BEACONS_RANGED: 'onBeaconsRanged',
+  ON_BEACON_REGION_EVENT: 'onBeaconRegionEvent',
+} as const;
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type BeaconData = {
+  uuid: string;
+  major: number;
+  minor: number;
+  /** Estimated distance in metres */
+  distance: number;
+  rssi: number;
+  /** 'immediate' | 'near' | 'far' | 'unknown' */
+  proximity: string;
+};
+
+export type BeaconRangedEvent = {
+  beacons: BeaconData[];
+  region: string;
+};
+
+export type BeaconRegionEvent = {
+  region: string;
+  /** 'enter' | 'exit' | 'determined' */
+  event: 'enter' | 'exit' | 'determined';
+  state?: 'inside' | 'outside' | 'unknown';
+};
+
+export type SpotnySdkConfig = {
+  /** Base URL for the backend API (default: https://api.spotny.app) */
+  backendURL?: string;
+  /** Maximum BLE detection distance in metres (default: 8.0) */
+  maxDetectionDistance?: number;
+};
+
+// ── Internal event emitter ───────────────────────────────────────────────────
+const eventEmitter = new NativeEventEmitter(NativeModules.SpotnySdk);
+
+// ── Core scanning ────────────────────────────────────────────────────────────
+
+/**
+ * Start beacon scanning.
+ * @param userUUID  A unique string identifying this installation / user session.
+ * @param userId    Optional authenticated user ID.
+ */
+export function startScanner(
+  userUUID: string,
+  userId?: number | null
+): Promise<string> {
+  return NativeSpotnySdk.startScanner(userUUID, userId ?? null);
+}
+
+/** Stop beacon scanning and clean up all state. */
+export function stopScanner(): Promise<string> {
+  return NativeSpotnySdk.stopScanner();
+}
+
+/** Returns `true` if the SDK is currently scanning. */
+export function isScanning(): Promise<boolean> {
+  return NativeSpotnySdk.isScanning();
+}
+
+// ── Configuration ────────────────────────────────────────────────────────────
+
+/**
+ * Override SDK configuration at runtime.
+ * Must be called **before** `startScanner`.
+ */
+export function configure(config: SpotnySdkConfig): Promise<string> {
+  return NativeSpotnySdk.configure(config as Object);
+}
+
+// ── Permissions ──────────────────────────────────────────────────────────────
+
+/** (iOS) Prompt the user for local-notification permissions. */
+export function requestNotificationPermissions(): Promise<string> {
+  return NativeSpotnySdk.requestNotificationPermissions();
+}
+
+// ── Debug helpers ─────────────────────────────────────────────────────────────
+
+/** Read the on-device debug log file. */
+export function getDebugLogs(): Promise<string> {
+  return NativeSpotnySdk.getDebugLogs();
+}
+
+/** Delete the on-device debug log file. */
+export function clearDebugLogs(): Promise<string> {
+  return NativeSpotnySdk.clearDebugLogs();
+}
+
+// ── Debounce helpers ──────────────────────────────────────────────────────────
+
+/** Override the proximity-event debounce interval (seconds). */
+export function setDebounceInterval(interval: number): Promise<string> {
+  return NativeSpotnySdk.setDebounceInterval(interval);
+}
+
+/** Clear the debounce / cooldown cache for all beacons. */
+export function clearDebounceCache(): Promise<string> {
+  return NativeSpotnySdk.clearDebounceCache();
+}
+
+/** Return the current debounce status for all tracked beacons. */
+export function getDebounceStatus(): Promise<Object> {
+  return NativeSpotnySdk.getDebounceStatus();
+}
+
+// ── Event subscriptions ───────────────────────────────────────────────────────
+
+/**
+ * Subscribe to continuous ranging updates.
+ * The callback fires roughly every second while beacons are in range.
+ */
+export function addBeaconsRangedListener(
+  callback: (event: BeaconRangedEvent) => void
+) {
+  return eventEmitter.addListener(
+    SpotnyEvents.ON_BEACONS_RANGED,
+    callback as (...args: readonly object[]) => unknown
+  );
+}
+
+/**
+ * Subscribe to region enter/exit events.
+ * These fire in all app states (foreground, background, terminated on iOS).
+ */
+export function addBeaconRegionListener(
+  callback: (event: BeaconRegionEvent) => void
+) {
+  return eventEmitter.addListener(
+    SpotnyEvents.ON_BEACON_REGION_EVENT,
+    callback as (...args: readonly object[]) => unknown
+  );
+}