spotny-sdk 0.3.2 → 0.3.3

package/README.md

@@ -1,26 +1,312 @@
 # spotny-sdk
 
-Beacon Scanner
+A React Native SDK for iBeacon scanning powered by KontaktSDK (iOS) and AltBeacon (Android). Detects proximity beacons, fires region enter/exit events, and integrates with the Spotny campaign backend.
 
-## Installation
+> Requires **React Native 0.73+** with the New Architecture (Turbo Modules) enabled.
+
+---
 
+## Installation
 
 ```sh
 npm install spotny-sdk
+# or
+yarn add spotny-sdk
+```
+
+### iOS
+
+```sh
+cd ios && pod install
 ```
 
+Add the following keys to your `Info.plist`:
 
-## Usage
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>We use your location to detect nearby beacons.</string>
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>We use your location in the background to detect nearby beacons.</string>
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>We use Bluetooth to scan for nearby beacons.</string>
+```
 
+Enable **Background Modes** in Xcode → Signing & Capabilities:
+- Location updates
+- Uses Bluetooth LE accessories
 
-```js
-import { multiply } from 'spotny-sdk';
+### Android
 
-// ...
+Add to `AndroidManifest.xml`:
 
-const result = multiply(3, 7);
+```xml
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
 ```
 
+---
+
+## Quick Start
+
+```tsx
+import { useEffect } from 'react';
+import {
+  configure,
+  startScanner,
+  stopScanner,
+  addBeaconsRangedListener,
+  addBeaconRegionListener,
+} from 'spotny-sdk';
+
+export default function App() {
+  useEffect(() => {
+    // Optional: override defaults before starting
+    configure({ maxDetectionDistance: 10 });
+
+    // Start scanning with a unique device/user identifier
+    startScanner('device-uuid-here', /* userId */ null);
+
+    // Listen for ranged beacons (fires ~every second)
+    const rangedSub = addBeaconsRangedListener(({ beacons, region }) => {
+      console.log('Beacons in range:', beacons);
+    });
+
+    // Listen for region enter / exit
+    const regionSub = addBeaconRegionListener(({ region, event }) => {
+      console.log(`Region ${region}: ${event}`);
+    });
+
+    return () => {
+      stopScanner();
+      rangedSub.remove();
+      regionSub.remove();
+    };
+  }, []);
+
+  return null;
+}
+```
+
+---
+
+## API Reference
+
+### Core Scanning
+
+#### `startScanner(userUUID, userId?)`
+
+Starts BLE beacon scanning and begins ranging / monitoring regions.
+
+| Parameter  | Type             | Required | Description                                      |
+|------------|------------------|----------|--------------------------------------------------|
+| `userUUID` | `string`         | Yes      | Unique identifier for this installation/session  |
+| `userId`   | `number \| null` | No       | Authenticated user ID (sent to the backend)      |
+
+Returns `Promise<string>` — resolves with a status message.
+
+```ts
+await startScanner('550e8400-e29b-41d4-a716-446655440000', 42);
+```
+
+---
+
+#### `stopScanner()`
+
+Stops scanning, halts ranging, and clears all in-memory beacon state.
+
+Returns `Promise<string>`.
+
+```ts
+await stopScanner();
+```
+
+---
+
+#### `isScanning()`
+
+Returns `Promise<boolean>` — `true` if the SDK is currently scanning.
+
+```ts
+const scanning = await isScanning();
+```
+
+---
+
+### Configuration
+
+#### `configure(config)`
+
+Overrides SDK defaults. **Must be called before `startScanner`.**
+
+| Option                | Type     | Default                    | Description                              |
+|-----------------------|----------|----------------------------|------------------------------------------|
+| `backendURL`          | `string` | `https://api.spotny.app`   | Base URL for the Spotny campaign API     |
+| `maxDetectionDistance`| `number` | `8.0`                      | Maximum beacon detection radius (metres) |
+
+Returns `Promise<string>`.
+
+```ts
+await configure({
+  backendURL: 'https://api.spotny.app',
+  maxDetectionDistance: 12,
+});
+```
+
+---
+
+### Permissions
+
+#### `requestNotificationPermissions()` *(iOS only)*
+
+Prompts the user for local-notification permissions. Safe to call on Android (no-op).
+
+Returns `Promise<string>`.
+
+```ts
+await requestNotificationPermissions();
+```
+
+---
+
+### Event Listeners
+
+#### `addBeaconsRangedListener(callback)`
+
+Fires approximately every second while beacons are within `maxDetectionDistance`.
+
+```ts
+const subscription = addBeaconsRangedListener(({ beacons, region }) => {
+  beacons.forEach(b => {
+    console.log(`${b.uuid} — ${b.distance.toFixed(1)} m (${b.proximity})`);
+  });
+});
+
+// When done:
+subscription.remove();
+```
+
+**Callback payload — `BeaconRangedEvent`:**
+
+| Field     | Type           | Description                    |
+|-----------|----------------|--------------------------------|
+| `beacons` | `BeaconData[]` | Array of visible beacons       |
+| `region`  | `string`       | Beacon region identifier       |
+
+**`BeaconData`:**
+
+| 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).
+
+```ts
+const subscription = addBeaconRegionListener(({ region, event, state }) => {
+  if (event === 'enter') console.log('Entered', region);
+  if (event === 'exit')  console.log('Exited', region);
+});
+
+// When done:
+subscription.remove();
+```
+
+**Callback payload — `BeaconRegionEvent`:**
+
+| Field    | Type     | Description                                             |
+|----------|----------|---------------------------------------------------------|
+| `region` | `string` | Region identifier                                       |
+| `event`  | `string` | `'enter'` \| `'exit'` \| `'determined'`                |
+| `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);
+```
+
+#### `clearDebugLogs()`
+
+Deletes the on-device debug log file.
+
+```ts
+await clearDebugLogs();
+```
+
+---
+
+## TypeScript Types
+
+```ts
+import type {
+  BeaconData,
+  BeaconRangedEvent,
+  BeaconRegionEvent,
+  SpotnySdkConfig,
+} from 'spotny-sdk';
+```
+
+---
+
+## Platform Notes
+
+| Feature                  | iOS | Android |
+|--------------------------|-----|---------|
+| Region monitoring        | ✅  | ✅      |
+| Background scanning      | ✅  | ✅      |
+| Terminated-state wakeup  | ✅  | ✅      |
+| Notification permissions | ✅  | –       |
+
+---
 
 ## Contributing
 
@@ -31,7 +317,3 @@ const result = multiply(3, 7);
 ## License
 
 MIT
-
----
-
-Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/package.json

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