spotny-sdk 1.0.2 → 1.0.4

package/README.md

@@ -267,7 +267,7 @@ Returns `Promise<Object>`.
 
 ## How It Works
 
-1. `initialize()` sends your `token`, `apiKey`, and `userId` to the Spotny backend, which issues a session JWT. The JWT is persisted locally and auto-refreshed when it expires.
+1. `initialize()` sends your `token`, `apiKey`, and `identifierId` to the Spotny backend, which issues a session JWT. The JWT is persisted locally and auto-refreshed when it expires.
 2. `startScanner()` begins monitoring for iBeacons with the Spotny UUID.
 3. When a beacon is detected, the SDK fetches the associated campaign from the Spotny backend.
 4. `NEARBY` events are sent automatically as the user moves closer or further.
@@ -301,289 +301,3 @@ All events are tied to the authenticated `identifierId` supplied during `initial
 ## License
 
 MIT
-
----
-
-## 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`:
-
-```xml
-<key>NSLocationWhenInUseUsageDescription</key>
-<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 points of interest.</string>
-<key>NSBluetoothAlwaysUsageDescription</key>
-<string>We use Bluetooth to detect nearby points of interest.</string>
-```
-
-Enable **Background Modes** in Xcode → your app target → **Signing & Capabilities** → Background Modes:
-
-- ✅ Location updates
-- ✅ Uses Bluetooth LE accessories
-
-### Android
-
-Add to `AndroidManifest.xml`:
-
-```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 {
-  initialize,
-  startScanner,
-  stopScanner,
-  addBeaconsRangedListener,
-  addBeaconRegionListener,
-} from 'spotny-sdk';
-
-export default function App() {
-  useEffect(() => {
-    // 1. Initialize once before anything else
-    initialize({
-      token: 'YOUR_SDK_TOKEN', // required — from your Spotny dashboard
-      source: 'nike',
-      maxDetectionDistance: 10,
-    });
-
-    // 2. Listen for nearby beacons
-    const beaconSub = addBeaconsRangedListener(({ beacons, region }) => {
-      beacons.forEach((b) =>
-        console.log(
-          `${b.major}/${b.minor} — ${b.distance.toFixed(1)}m (${b.proximity})`
-        )
-      );
-    });
-
-    // 3. Listen for region enter/exit
-    const regionSub = addBeaconRegionListener(({ event, region }) => {
-      console.log(`${event.toUpperCase()}: ${region}`);
-    });
-
-    // 4. Start scanning
-    startScanner();
-
-    return () => {
-      stopScanner();
-      beaconSub.remove();
-      regionSub.remove();
-    };
-  }, []);
-
-  return null;
-}
-```
-
----
-
-## API Reference
-
-### Initialization
-
-#### `initialize(config)`
-
-**Must be called before any other SDK function.** Configures the SDK with your brand settings.
-
-| Option                     | Type     | Default      | Description                                                                                                     |
-| -------------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
-| `token`                    | `string` | **required** | SDK token issued by Spotny for your app. Verified against the backend — rejects with `UNAUTHORIZED` if invalid. |
-| `source`                   | `string` | –            | Your brand or app identifier (e.g. `'nike'`). Sent with every tracking event.                                   |
-| `maxDetectionDistance`     | `number` | `8.0`        | Maximum detection radius in metres. Beacons beyond this are ignored.                                            |
-| `distanceCorrectionFactor` | `number` | `0.5`        | Multiplier applied to raw RSSI distance. Tune for your beacon TX power.                                         |
-
-Returns `Promise<string>`. **Rejects** if the token is missing, invalid, or the network request fails — handle the error before calling `startScanner()`.
-
-```ts
-await initialize({
-  token: 'YOUR_SDK_TOKEN',
-  source: 'nike',
-  maxDetectionDistance: 10,
-  distanceCorrectionFactor: 0.5,
-});
-```
-
----
-
-### Core Scanning
-
-#### `startScanner()`
-
-Starts iBeacon scanning. The SDK manages a fully anonymous `device_id` internally (stored in Keychain on iOS, SharedPreferences on Android — persists across launches).
-
-Returns `Promise<string>`.
-
-```ts
-await startScanner();
-```
-
----
-
-#### `stopScanner()`
-
-Stops scanning and cleans up all per-beacon state (sends `PROXIMITY_EXIT` events for any active beacons).
-
-Returns `Promise<string>`.
-
----
-
-#### `isScanning()`
-
-Returns `Promise<boolean>` — `true` if the scanner is currently active.
-
----
-
-### Permissions
-
-#### `requestNotificationPermissions()` _(iOS only)_
-
-Prompts the user for local notification permission (`alert`, `sound`, `badge`).
-
-Returns `Promise<'granted' | 'denied'>`.
-
----
-
-### Event Listeners
-
-#### `addBeaconsRangedListener(callback)`
-
-Fires when the set of nearby beacons changes, or every `debounceInterval` seconds (default 5 s) if nothing changed. The event is **deduplicated** — it does not fire every ranging cycle if proximity is unchanged.
-
-```ts
-const sub = addBeaconsRangedListener(({ beacons, region }) => {
-  beacons.forEach((b) => {
-    console.log(`Major ${b.major} / Minor ${b.minor}`);
-    console.log(`Distance: ${b.distance.toFixed(2)}m — ${b.proximity}`);
-    console.log(`RSSI: ${b.rssi} dBm`);
-  });
-});
-
-sub.remove(); // call on cleanup
-```
-
-Each beacon in the array:
-
-| Field       | Type     | Description                                                    |
-| ----------- | -------- | -------------------------------------------------------------- |
-| `uuid`      | `string` | Beacon proximity UUID                                          |
-| `major`     | `number` | Beacon major value                                             |
-| `minor`     | `number` | Beacon minor value                                             |
-| `distance`  | `number` | Estimated distance in metres (after correction factor applied) |
-| `rssi`      | `number` | Raw signal strength in dBm                                     |
-| `proximity` | `string` | `'immediate'` \| `'near'` \| `'far'` \| `'unknown'`            |
-
----
-
-#### `addBeaconRegionListener(callback)`
-
-Fires when the user enters or exits a beacon region. Works in foreground, background, and terminated state (iOS).
-
-```ts
-const sub = addBeaconRegionListener(({ event, region, state }) => {
-  if (event === 'enter') console.log('Entered region', region);
-  if (event === 'exit') console.log('Left region', region);
-  if (event === 'determined') console.log('State for', region, '→', state);
-});
-
-sub.remove(); // call on cleanup
-```
-
-| Field    | Type     | Description                                                        |
-| -------- | -------- | ------------------------------------------------------------------ |
-| `event`  | `string` | `'enter'` \| `'exit'` \| `'determined'`                            |
-| `region` | `string` | Region identifier                                                  |
-| `state`  | `string` | `'inside'` \| `'outside'` \| `'unknown'` (`determined` event only) |
-
----
-
-### Debug Helpers
-
-#### `getDebugLogs()`
-
-Returns the on-device debug log file as a string. Includes campaign fetch results and proximity events sent.
-
-Returns `Promise<string>`.
-
-#### `clearDebugLogs()`
-
-Clears the on-device debug log file.
-
-Returns `Promise<string>`.
-
-#### `setDebounceInterval(seconds)`
-
-Sets how often the `onBeaconsRanged` event is force-emitted even if proximity hasn't changed (default: `5`).
-
-```ts
-await setDebounceInterval(10); // emit at most every 10 s
-```
-
-#### `clearDebounceCache()`
-
-Resets internal campaign-fetch cooldown state. Useful during testing.
-
-#### `getDebounceStatus()`
-
-Returns internal per-beacon timing state. Useful for debugging stuck campaigns.
-
-Returns `Promise<Object>`.
-
----
-
-## How It Works
-
-1. `initialize()` sets your brand config.
-2. `startScanner()` begins monitoring for iBeacons with the Spotny UUID.
-3. When a beacon is detected, the SDK fetches the associated campaign from the Spotny backend.
-4. `NEARBY` events are sent automatically as the user moves closer or further.
-5. `IMPRESSION_HEARTBEAT` events are sent every 10 s when the user is within 2 m of an active campaign.
-6. On exit, `PROXIMITY_EXIT` is sent and all state is cleaned up.
-
-The SDK is **fully anonymous** — it generates a persistent `device_id` (Keychain on iOS, SharedPreferences on Android) that survives app reinstalls. No user identity is collected or sent.
-
----
-
-## Platform Support
-
-| Feature                  | iOS | Android |
-| ------------------------ | --- | ------- |
-| iBeacon ranging          | ✅  | ✅      |
-| Region enter/exit        | ✅  | ✅      |
-| Background scanning      | ✅  | ✅      |
-| Terminated-state wakeup  | ✅  | ✅      |
-| Keychain device ID       | ✅  | –       |
-| Notification permissions | ✅  | –       |
-
----
-
-## Contributing
-
-- [Development workflow](CONTRIBUTING.md#development-workflow)
-- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
-- [Code of conduct](CODE_OF_CONDUCT.md)
-
-## License
-
-MIT

package/package.json

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