spotny-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Freijeh
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,589 @@
+# spotny-sdk
+
+A React Native SDK for real-time iBeacon proximity experiences. Detects nearby beacons, fetches campaigns, and fires tracking events automatically on iOS and Android — all tied to your authenticated user.
+
+> 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`:
+
+```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 — call after the user is logged in
+    initialize({
+      token: 'YOUR_SDK_TOKEN', // from your Spotny dashboard
+      apiKey: 'your-brand-key', // identifies your app/brand
+      userId: currentUser.id, // your authenticated user ID
+      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.** Authenticates with the Spotny backend and obtains a session JWT that is automatically used for all subsequent API calls.
+
+| Option                     | Type     | Default      | Description                                                                                                                                |
+| -------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `token`                    | `string` | **required** | SDK token issued by Spotny for your app. Verified against the backend — rejects with `UNAUTHORIZED` if invalid.                            |
+| `apiKey`                   | `string` | **required** | Identifies your brand or app (e.g. `'nike'`). Sent to the backend during verification.                                                     |
+| `userId`                   | `string` | **required** | ID of the authenticated user (e.g. database UUID, hashed email). Embedded in the session JWT so all tracking events are tied to this user. |
+| `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 any required field is missing, the token is invalid, or the network request fails — handle the error before calling `startScanner()`.
+
+> **Note:** The SDK is designed for authenticated (logged-in) users. Call `initialize()` after the user has signed in so their `userId` is available.
+
+```ts
+await initialize({
+  token: 'YOUR_SDK_TOKEN',
+  apiKey: 'nike',
+  userId: currentUser.id,
+  maxDetectionDistance: 10,
+  distanceCorrectionFactor: 0.5,
+});
+```
+
+#### JWT persistence & auto-refresh
+
+The session JWT returned by `initialize()` is persisted to **Keychain** (iOS) / **SharedPreferences** (Android) and automatically restored when the app relaunches — so scanning resumes without calling `initialize()` again after a force-quit or crash.
+
+If the JWT expires mid-session, the SDK transparently re-fetches it before the next API call. No action is required from your app.
+
+---
+
+### Core Scanning
+
+#### `startScanner()`
+
+Starts iBeacon scanning. The SDK manages a persistent `device_id` internally (Keychain on iOS, SharedPreferences on Android — survives reinstalls).
+
+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()` 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.
+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.
+
+All events are tied to the authenticated `userId` supplied during `initialize()` — no additional identity calls are required.
+
+---
+
+## Platform Support
+
+| Feature                  | iOS | Android |
+| ------------------------ | --- | ------- |
+| iBeacon ranging          | ✅  | ✅      |
+| Region enter/exit        | ✅  | ✅      |
+| Background scanning      | ✅  | ✅      |
+| Terminated-state wakeup  | ✅  | ✅      |
+| JWT persistence          | ✅  | ✅      |
+| 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
+
+---
+
+## 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/SpotnySdk.podspec

@@ -0,0 +1,35 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "SpotnySdk"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/Spotny-SA/spotny-sdk.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  # All three frameworks are pre-built with Swift 6.2 and bundled — no SPM or manual setup needed.
+  # DO NOT also add KontaktSDK/CBORCoding/Half via SPM — it causes duplicate framework errors.
+  s.vendored_frameworks = [
+    "ios/Frameworks/KontaktSDK.xcframework",
+    "ios/Frameworks/CBORCoding.xcframework",
+    "ios/Frameworks/Half.xcframework"
+  ]
+
+
+
+  s.pod_target_xcconfig = {
+    "SWIFT_VERSION" => "5.0",
+    "CLANG_ENABLE_MODULES" => "YES"
+  }
+
+  install_modules_dependencies(s)
+end