spotny-sdk 0.3.8 → 0.3.9

package/README.md

@@ -1,6 +1,6 @@
 # spotny-sdk
 
-A React Native SDK for iBeacon proximity detection. Detects nearby beacons, fires region enter/exit events, and powers real-time proximity experiences on iOS and Android.
+A React Native SDK for real-time proximity experiences. Detects nearby points of interest and fires location events on iOS and Android.
 
 > Requires **React Native 0.73+** with the New Architecture (Turbo Modules) enabled.
 
@@ -24,11 +24,11 @@ Add the following keys to your `Info.plist`:
 
 ```xml
 <key>NSLocationWhenInUseUsageDescription</key>
-<string>We use your location to detect nearby beacons.</string>
+<string>We use your location to detect nearby points of interest.</string>
 <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
-<string>We use your location in the background to detect nearby beacons.</string>
+<string>We use your location in the background to detect nearby points of interest.</string>
 <key>NSBluetoothAlwaysUsageDescription</key>
-<string>We use Bluetooth to scan for nearby beacons.</string>
+<string>We use Bluetooth to detect nearby points of interest.</string>
 ```
 
 Enable **Background Modes** in Xcode → your app target → **Signing & Capabilities** → **+ Capability** → Background Modes:
@@ -36,7 +36,7 @@ Enable **Background Modes** in Xcode → your app target → **Signing & Capabil
 - ✅ Location updates
 - ✅ Uses Bluetooth LE accessories
 
-> **Important — avoid crash on launch:** If your app does **not** enable the _Location updates_ background mode, the SDK will still work for foreground-only scanning. However, if you enable it in Xcode, the `UIBackgroundModes: [location]` entry is added to `Info.plist` and the SDK will automatically enable background scanning. Omitting this while calling `startScanner` is safe — the SDK detects the missing capability at runtime and skips the background-location setting. Earlier versions (< 0.3.4) would crash with `NSInternalInconsistencyException` if the background mode was not declared; this is fixed in **0.3.4+**.
+> **Note:** Background scanning requires the _Location updates_ background mode. The SDK works without it for foreground-only use.
 
 ### Android
 
@@ -60,32 +60,28 @@ import {
   configure,
   startScanner,
   stopScanner,
-  addBeaconsRangedListener,
-  addBeaconRegionListener,
+  addProximityListener,
+  addLocationEventListener,
 } from 'spotny-sdk';
 
 export default function App() {
   useEffect(() => {
-    // Optional: override defaults before starting
-    configure({ maxDetectionDistance: 10 });
-
-    // Start scanning with a unique device/user identifier
+    configure({ source: 'nike', maxDetectionDistance: 10 });
     startScanner('device-uuid-here', /* userId */ null);
 
-    // Listen for ranged beacons (fires ~every second)
-    const rangedSub = addBeaconsRangedListener(({ beacons, region }) => {
-      console.log('Beacons in range:', beacons);
+    const proxSub = addProximityListener((items) => {
+      console.log('Nearby:', items);
     });
 
-    // Listen for region enter / exit
-    const regionSub = addBeaconRegionListener(({ region, event }) => {
-      console.log(`Region ${region}: ${event}`);
+    const locationSub = addLocationEventListener(({ event, zone }) => {
+      if (event === 'enter') console.log('Entered zone', zone);
+      if (event === 'exit') console.log('Left zone', zone);
     });
 
     return () => {
       stopScanner();
-      rangedSub.remove();
-      regionSub.remove();
+      proxSub.remove();
+      locationSub.remove();
     };
   }, []);
 
@@ -97,18 +93,18 @@ export default function App() {
 
 ## API Reference
 
-### Core Scanning
+### Core
 
 #### `startScanner(userUUID, userId?)`
 
-Starts BLE beacon scanning and begins ranging / monitoring regions.
+Starts proximity scanning.
 
-| Parameter  | Type             | Required | Description                                     |
-| ---------- | ---------------- | -------- | ----------------------------------------------- |
-| `userUUID` | `string`         | Yes      | Unique identifier for this installation/session |
-| `userId`   | `number \| null` | No       | Authenticated user ID                           |
+| Parameter  | Type             | Required | Description                               |
+| ---------- | ---------------- | -------- | ----------------------------------------- |
+| `userUUID` | `string`         | Yes      | Unique identifier for this device/session |
+| `userId`   | `number \| null` | No       | Authenticated user ID                     |
 
-Returns `Promise<string>` — resolves with a status message.
+Returns `Promise<string>`.
 
 ```ts
 await startScanner('550e8400-e29b-41d4-a716-446655440000', 42);
@@ -118,23 +114,15 @@ await startScanner('550e8400-e29b-41d4-a716-446655440000', 42);
 
 #### `stopScanner()`
 
-Stops scanning, halts ranging, and clears all in-memory beacon state.
+Stops scanning and clears all state.
 
 Returns `Promise<string>`.
 
-```ts
-await stopScanner();
-```
-
 ---
 
 #### `isScanning()`
 
-Returns `Promise<boolean>` — `true` if the SDK is currently scanning.
-
-```ts
-const scanning = await isScanning();
-```
+Returns `Promise<boolean>`.
 
 ---
 
@@ -142,17 +130,15 @@ const scanning = await isScanning();
 
 #### `configure(config)`
 
-Overrides SDK defaults. **Must be called before `startScanner`.**
-
-| Option                 | Type     | Default | Description                                                                     |
-| ---------------------- | -------- | ------- | ------------------------------------------------------------------------------- |
-| `maxDetectionDistance` | `number` | `8.0`   | Maximum beacon detection radius (metres)                                        |
-| `source`               | `string` | –       | Identifier for your brand or app (e.g. `'nike'`). |
+Call **before** `startScanner`.
 
-Returns `Promise<string>`.
+| Option                 | Type     | Default | Description                                  |
+| ---------------------- | -------- | ------- | -------------------------------------------- |
+| `source`               | `string` | –       | Your brand or app identifier (e.g. `'nike'`) |
+| `maxDetectionDistance` | `number` | `8.0`   | Detection radius in metres                   |
 
 ```ts
-await configure({ maxDetectionDistance: 12, source: 'nike' });
+await configure({ source: 'nike', maxDetectionDistance: 10 });
 ```
 
 ---
@@ -161,139 +147,66 @@ await configure({ maxDetectionDistance: 12, source: 'nike' });
 
 #### `requestNotificationPermissions()` _(iOS only)_
 
-Prompts the user for local-notification permissions. Safe to call on Android (no-op).
+Requests local notification permissions.
 
 Returns `Promise<string>`.
 
-```ts
-await requestNotificationPermissions();
-```
-
 ---
 
 ### Event Listeners
 
 #### `addBeaconsRangedListener(callback)`
 
-Fires approximately every second while beacons are within `maxDetectionDistance`.
+Fires when nearby items are detected (approximately every second).
 
 ```ts
-const subscription = addBeaconsRangedListener(({ beacons, region }) => {
-  beacons.forEach((b) => {
-    console.log(`${b.uuid} — ${b.distance.toFixed(1)} m (${b.proximity})`);
+const sub = addBeaconsRangedListener(({ beacons }) => {
+  beacons.forEach((item) => {
+    console.log(`${item.distance.toFixed(1)} m — ${item.proximity}`);
   });
 });
 
-// When done:
-subscription.remove();
+sub.remove(); // when done
 ```
 
-**Callback payload — `BeaconRangedEvent`:**
-
-| Field     | Type           | Description              |
-| --------- | -------------- | ------------------------ |
-| `beacons` | `BeaconData[]` | Array of visible beacons |
-| `region`  | `string`       | Beacon region identifier |
-
-**`BeaconData`:**
+Each item contains:
 
 | Field       | Type     | Description                                         |
 | ----------- | -------- | --------------------------------------------------- |
-| `uuid`      | `string` | Proximity UUID                                      |
-| `major`     | `number` | Major value                                         |
-| `minor`     | `number` | Minor value                                         |
 | `distance`  | `number` | Estimated distance in metres                        |
-| `rssi`      | `number` | Signal strength (dBm)                               |
 | `proximity` | `string` | `'immediate'` \| `'near'` \| `'far'` \| `'unknown'` |
 
 ---
 
 #### `addBeaconRegionListener(callback)`
 
-Fires on region enter, exit, and state-determination events. Works in **foreground, background, and terminated state** (iOS).
+Fires when the user enters or exits a zone. Works in foreground, background, and terminated state (iOS).
 
 ```ts
-const subscription = addBeaconRegionListener(({ region, event, state }) => {
-  if (event === 'enter') console.log('Entered', region);
-  if (event === 'exit') console.log('Exited', region);
+const sub = addBeaconRegionListener(({ event, region, state }) => {
+  console.log(event, region); // 'enter' | 'exit' | 'determined'
 });
 
-// When done:
-subscription.remove();
+sub.remove(); // when done
 ```
 
-**Callback payload — `BeaconRegionEvent`:**
-
 | Field    | Type     | Description                                                |
 | -------- | -------- | ---------------------------------------------------------- |
-| `region` | `string` | Region identifier                                          |
 | `event`  | `string` | `'enter'` \| `'exit'` \| `'determined'`                    |
+| `region` | `string` | Zone identifier                                            |
 | `state`  | `string` | `'inside'` \| `'outside'` \| `'unknown'` (determined only) |
 
 ---
 
-### Debounce Helpers
-
-These let you tune how often repeated proximity events are emitted for the same beacon.
-
-#### `setDebounceInterval(seconds)`
-
-Sets the minimum gap (in seconds) between proximity events for the same beacon.
-
-```ts
-await setDebounceInterval(30); // fire at most once per 30 s per beacon
-```
-
-#### `clearDebounceCache()`
-
-Resets cooldown state for all beacons, allowing them to fire again immediately.
-
-```ts
-await clearDebounceCache();
-```
-
-#### `getDebounceStatus()`
-
-Returns the current cooldown state for all tracked beacons.
-
-```ts
-const status = await getDebounceStatus();
-console.log(status);
-```
-
----
-
 ### Debug Helpers
 
 #### `getDebugLogs()`
 
-Reads the on-device debug log file.
-
-```ts
-const logs = await getDebugLogs();
-console.log(logs);
-```
+Returns on-device debug logs as a string.
 
 #### `clearDebugLogs()`
 
-Deletes the on-device debug log file.
-
-```ts
-await clearDebugLogs();
-```
-
----
-
-## TypeScript Types
-
-```ts
-import type {
-  BeaconData,
-  BeaconRangedEvent,
-  BeaconRegionEvent,
-  SpotnySdkConfig,
-} from 'spotny-sdk';
-```
+Clears on-device debug logs.
 
 ---
 
@@ -301,7 +214,7 @@ import type {
 
 | Feature                  | iOS | Android |
 | ------------------------ | --- | ------- |
-| Region monitoring        | ✅  | ✅      |
+| Zone monitoring          | ✅  | ✅      |
 | Background scanning      | ✅  | ✅      |
 | Terminated-state wakeup  | ✅  | ✅      |
 | Notification permissions | ✅  | –       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spotny-sdk",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Beacon Scanner",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",