spotny-sdk 1.0.0

package/src/index.tsx

@@ -0,0 +1,151 @@
+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 = {
+  /**
+   * SDK token issued by Spotny for your app.
+   * Sent to the backend during initialize() to obtain a session JWT. Required.
+   */
+  token: string;
+  /**
+   * API key identifying your brand or app (e.g. 'nike').
+   * Sent to the backend during initialize() alongside the token. Required.
+   */
+  apiKey: string;
+  /**
+   * ID of the authenticated user (e.g. database UUID, hashed email).
+   * Embedded in the JWT so all tracking events are tied to this user. Required.
+   */
+  userId: string;
+  /** Maximum BLE detection distance in metres (default: 8.0) */
+  maxDetectionDistance?: number;
+  /**
+   * Multiplier applied to raw RSSI-derived distance to compensate for device
+   * TX power variance (default: 0.5, tuned for Kontakt.io -12 dBm beacons).
+   */
+  distanceCorrectionFactor?: number;
+};
+
+// ── Internal event emitter ───────────────────────────────────────────────────
+const eventEmitter = new NativeEventEmitter(NativeModules.SpotnySdk);
+
+// ── Core scanning ────────────────────────────────────────────────────────────
+
+/** Start beacon scanning. */
+export function startScanner(): Promise<string> {
+  return NativeSpotnySdk.startScanner();
+}
+
+/** 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();
+}
+
+// ── Initialization ──────────────────────────────────────────────────────────────
+
+/**
+ * Initialize the SDK. Must be called **before** any other SDK function.
+ */
+export function initialize(config: SpotnySdkConfig): Promise<string> {
+  return NativeSpotnySdk.initialize(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
+  );
+}