react-native-cliqit 0.0.1

package/README.md

@@ -0,0 +1,209 @@
+# react-native-cliqit
+
+React Native bridge for **CliqIt** deferred deep linking.
+
+- **iOS:** ships `CliqIt.xcframework` (closed-source native SDK)
+- **Android:** Kotlin SDK + RN bridge included
+- **No npm publish required** — install from Git
+
+**Version:** `2.0.6`
+
+## Install (Git)
+
+```bash
+npm install git+https://github.com/mindrootstech/react-native-cliqit.git#v2.0.6
+# or yarn / pnpm equivalent
+
+cd ios && pod install && cd ..
+```
+
+`package.json`:
+
+```json
+"dependencies": {
+  "react-native-cliqit": "git+https://github.com/mindrootstech/react-native-cliqit.git#v2.0.6"
+}
+```
+
+## Usage
+
+All APIs use a `{ result, error }` callback object.
+
+Register listeners **before** `configure` — deferred match can finish very fast.
+
+```js
+import { useEffect } from 'react';
+import { Linking } from 'react-native';
+import CliqIt from 'react-native-cliqit';
+
+useEffect(() => {
+  // onDeepLink — runs when the app should navigate:
+  //   • Direct: user opens a SmartLink / App Link while app is installed (isDeferred: false)
+  //   • Deferred: after a successful first-open match, SDK delivers the path (isDeferred: true)
+  const offDeepLink = CliqIt.onDeepLink(({ result, error }) => {
+    if (error) return;
+    console.log('deep link', result.path, result.isDeferred);
+  });
+
+  // onDeferredMatch — runs once on cold start / configure (first install attribution):
+  //   Server fingerprint match result (matched / notMatched / alreadyReported + score/slug/path).
+  //   Does NOT mean "navigate by itself" — if matched, onDeepLink usually fires next.
+  const offMatch = CliqIt.onDeferredMatch(({ result, error }) => {
+    if (error) return;
+    if (result?.status === 'matched') {
+      console.log('deferred', result.destinationPath);
+    }
+  });
+
+  // onLinkLookup — runs on direct SmartLink open when SDK resolves slug → destination via API.
+  //   Not used for pure deferred-only first open (unless a URL was also handled).
+  const offLookup = CliqIt.onLinkLookup(({ result, error }) => {
+    if (error) return;
+    console.log('link lookup', result?.resolvedPath ?? result?.slug);
+  });
+
+  // onVerify — runs after configure (background): API key + package/bundle (/ SHA) identity check.
+  const offVerify = CliqIt.onVerify(({ result, error }) => {
+    console.log('verify', error || result?.status);
+  });
+
+  // configure — call once at startup (after listeners). Starts verify + deferred match.
+  CliqIt.configure({ apiKey: 'pk_live_…' }, ({ result, error }) => {
+    console.log('configured', result, error);
+  });
+
+  // handleUrl — pass Universal Links / App Links / custom-scheme URLs into the SDK.
+  //   Cold start: Linking.getInitialURL(). Warm: Linking 'url' event.
+  Linking.getInitialURL().then((url) => {
+    if (url) CliqIt.handleUrl({ url }, ({ error }) => {});
+  });
+  const linkSub = Linking.addEventListener('url', ({ url }) => {
+    CliqIt.handleUrl({ url });
+  });
+
+  return () => {
+    offDeepLink();
+    offMatch();
+    offLookup();
+    offVerify();
+    linkSub.remove();
+  };
+}, []);
+```
+
+
+## Callback results
+
+Every listener / action callback receives:
+
+```ts
+{ result: object | null, error: string | null }
+```
+
+- On success: `error` is `null`, use `result`
+- On failure: `result` is `null`, use `error`
+
+### `configure({ apiKey }, cb)`
+
+| Field | Type | Notes |
+|-------|------|--------|
+| `result.ok` | `boolean` | `true` when configure was accepted locally |
+| `error` | `string` | Missing `apiKey`, or native throw |
+
+Starts background **verify** + **deferred match** (listeners should be registered first).
+
+### `handleUrl({ url }, cb)`
+
+| Field | Type | Notes |
+|-------|------|--------|
+| `result.ok` | `boolean` | URL was passed into the native SDK |
+| `result.url` | `string` | Same URL you passed |
+| `error` | `string` | Missing / invalid `url` |
+
+Use for Universal Links / App Links / custom schemes (cold start + warm).
+
+### `onDeepLink(({ result, error }) => …)`
+
+Navigation payload — **direct** opens and **deferred delivery**.
+
+| Field | Type | Notes |
+|-------|------|--------|
+| `result.url` | `string` | Original or synthetic URL |
+| `result.path` | `string` | In-app path (usually starts with `/`) |
+| `result.pathComponents` | `string[]` | Path segments |
+| `result.query` | `object` | Query key → value |
+| `result.source` | `string` | e.g. `deferred`, `universalLink`, `customScheme` |
+| `result.isDeferred` | `boolean` | `true` if from deferred match delivery |
+| `error` | `string` | Rare bridge/payload issues |
+
+### `onDeferredMatch(({ result, error }) => …)`
+
+First-open **attribution** only (not navigation by itself).
+
+| Field | Type | When |
+|-------|------|------|
+| `result.status` | `string` | `matched` \| `notMatched` \| `alreadyReported` |
+| `result.destinationPath` | `string?` | Matched in-app destination (may omit leading `/`) |
+| `result.slug` | `string?` | SmartLink slug |
+| `result.score` | `number?` | Match score |
+| `result.tier` | `string?` | e.g. `probabilistic` |
+| `result.confidence` | `string?` | e.g. `medium` |
+| `result.note` | `string?` | Present when `alreadyReported` |
+| `error` | `string` | Match request / decode failure (`status: failed`) |
+
+If `status === 'matched'`, `onDeepLink` usually fires next with `isDeferred: true`.
+
+### `onLinkLookup(({ result, error }) => …)`
+
+Direct SmartLink **slug → destination** API resolve.
+
+| Field | Type | Notes |
+|-------|------|--------|
+| `result.status` | `string` | `resolved` on success |
+| `result.resolvedPath` | `string?` | Platform path (`iosDestination` / `androidDestination` / `destination`) |
+| `result.slug` | `string?` | Link slug |
+| `result.destination` | `string?` | Default destination |
+| `result.iosDestination` | `string?` | iOS-specific path |
+| `result.androidDestination` | `string?` | Android-specific path |
+| `result.ogTitle` / `ogDescription` / `ogImage` / `ogUrl` | `string?` | Open Graph fields |
+| `result.webFallback` | `string?` | Web fallback URL |
+| `result.showInterstitial` | `string?` | `"true"` / `"false"` when present |
+| `result.isDeepLink` | `string?` | `"true"` / `"false"` when present |
+| `result.appleTeamId` | `string?` | iOS team id |
+| `result.iosBundleId` | `string?` | Expected iOS bundle |
+| `result.androidPackageName` | `string?` | Expected Android package |
+| `error` | `string` | Lookup failed |
+
+Prefer `CliqIt.LinkField.resolvedPath` (and other `LinkField` keys) instead of raw strings.
+
+### `onVerify(({ result, error }) => …)`
+
+Runs after `configure` — API key / app identity check.
+
+| Field | Type | Notes |
+|-------|------|--------|
+| `result.status` | `string` | `ok` \| `mismatch` |
+| `result.ok` | `boolean` | Same as server `ok` |
+| `result.appId` | `string?` | App id from admin |
+| `result.appName` | `string?` | App display name |
+| `result.message` | `string?` | Human-readable summary |
+| `result.checks` | `object?` | Per-field `{ actual, expected, match }` (bundle / package / SHA) |
+| `result.raw` | `string?` | Raw JSON body (if provided by native) |
+| `error` | `string` | Network / decode / failed verify transport |
+
+`mismatch` stays in `result` (identity problem, not a dropped callback). Transport failures use `error`.
+
+## App setup
+
+### iOS
+- Associated Domains: `applinks:<your-smartlink-domain>`
+- iOS 15+
+
+### Android
+- App Links intent-filter for your SmartLink host
+- Autolinking registers `CliqItPackage` (RN 0.60+)
+
+## Notes
+
+- This repo is **SDK only** — no demo app code.
+- Native iOS binary alone (without RN): https://github.com/mindrootstech/CliqIt

package/android/build.gradle

@@ -0,0 +1,27 @@
+buildscript {
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+
+android {
+  namespace "com.cliqit"
+  compileSdkVersion safeExtGet('compileSdkVersion', 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 24)
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs = ['src/main/java']
+    }
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/cliqit/CliqItModule.kt

@@ -0,0 +1,242 @@
+package com.cliqit
+
+import com.cliqit.sdk.CliqItSDK
+import com.cliqit.sdk.DeferredMatchOutcome
+import com.cliqit.sdk.LinkField
+import com.cliqit.sdk.LinkLookupResult
+import com.cliqit.sdk.VerifyOutcome
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
+
+class CliqItModule(private val reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  private var hasListeners = false
+  private var pendingDeepLink: WritableMap? = null
+  private var pendingDeferredMatch: WritableMap? = null
+  private var pendingLinkLookup: WritableMap? = null
+  private var pendingVerify: WritableMap? = null
+  private var handlersBound = false
+
+  override fun getName(): String = "CliqItModule"
+
+  override fun getConstants(): MutableMap<String, Any> = hashMapOf(
+    "LinkField" to hashMapOf(
+      "destination" to LinkField.destination,
+      "iosDestination" to LinkField.iosDestination,
+      "androidDestination" to LinkField.androidDestination,
+      "ogTitle" to LinkField.ogTitle,
+      "ogDescription" to LinkField.ogDescription,
+      "ogImage" to LinkField.ogImage,
+      "ogUrl" to LinkField.ogUrl,
+      "slug" to LinkField.slug,
+      "webFallback" to LinkField.webFallback,
+      "showInterstitial" to LinkField.showInterstitial,
+      "isDeepLink" to LinkField.isDeepLink,
+      "appleTeamId" to LinkField.appleTeamId,
+      "iosBundleId" to LinkField.iosBundleId,
+      "androidPackageName" to LinkField.androidPackageName,
+      "resolvedPath" to LinkField.resolvedPath,
+    ),
+  )
+
+  @ReactMethod
+  fun addListener(eventName: String) {
+    hasListeners = true
+    flushPending()
+  }
+
+  @ReactMethod
+  fun removeListeners(count: Int) {
+    if (count > 0) hasListeners = false
+  }
+
+  @ReactMethod
+  fun configure(apiKey: String) {
+    CliqItSDK.init(reactContext)
+    bindHandlersIfNeeded()
+    CliqItSDK.configure(apiKey)
+
+    if (CliqItSDK.hasDeferredMatchBeenReported && !CliqItSDK.isDeferredMatchInFlight) {
+      emitOrBuffer(
+        "CliqItDeferredMatch",
+        Arguments.createMap().apply {
+          putString("status", "alreadyReported")
+          putString(
+            "note",
+            "Deferred match already ran on this install. Clear app data to retest.",
+          )
+        },
+      ) { pendingDeferredMatch = it }
+    }
+  }
+
+  @ReactMethod
+  fun handleUrl(url: String) {
+    CliqItSDK.init(reactContext)
+    CliqItSDK.handle(url)
+  }
+
+  private fun bindHandlersIfNeeded() {
+    if (handlersBound) return
+    handlersBound = true
+
+    CliqItSDK.onDeepLink { payload ->
+      val query = Arguments.createMap()
+      payload.query.forEach { (k, v) -> query.putString(k, v) }
+      val components = Arguments.createArray()
+      payload.pathComponents.forEach { components.pushString(it) }
+      val map = Arguments.createMap().apply {
+        putString("url", payload.url)
+        putString("path", payload.path)
+        putArray("pathComponents", components)
+        putMap("query", query)
+        putString("source", payload.source)
+        putBoolean("isDeferred", payload.isDeferred)
+      }
+      emitOrBuffer("CliqItDeepLink", map) { pendingDeepLink = it }
+    }
+
+    CliqItSDK.onDeferredMatch { outcome ->
+      val map = Arguments.createMap()
+      when (outcome) {
+        is DeferredMatchOutcome.Matched -> {
+          map.putString("status", "matched")
+          putOpt(map, "destinationPath", outcome.info.destinationPath)
+          putOpt(map, "slug", outcome.info.slug)
+          putOpt(map, "tier", outcome.info.tier)
+          putOpt(map, "confidence", outcome.info.confidence)
+          outcome.info.score?.let { map.putDouble("score", it) }
+        }
+        is DeferredMatchOutcome.NotMatched -> {
+          map.putString("status", "notMatched")
+          putOpt(map, "tier", outcome.info.tier)
+          outcome.info.score?.let { map.putDouble("score", it) }
+        }
+        is DeferredMatchOutcome.Failed -> {
+          map.putString("status", "failed")
+          map.putString("error", outcome.error)
+        }
+      }
+      emitOrBuffer("CliqItDeferredMatch", map) { pendingDeferredMatch = it }
+    }
+
+    CliqItSDK.onDirectLinkLookup { result ->
+      val map = Arguments.createMap()
+      when (result) {
+        is LinkLookupResult.Resolved -> {
+          val d = result.details
+          map.putString("status", "resolved")
+          putOpt(map, LinkField.destination, d.destination)
+          putOpt(map, LinkField.iosDestination, d.iosDestination)
+          putOpt(map, LinkField.androidDestination, d.androidDestination)
+          putOpt(map, LinkField.ogTitle, d.ogTitle)
+          putOpt(map, LinkField.ogDescription, d.ogDescription)
+          putOpt(map, LinkField.ogImage, d.ogImage)
+          putOpt(map, LinkField.ogUrl, d.ogUrl)
+          putOpt(map, LinkField.slug, d.slug)
+          putOpt(map, LinkField.webFallback, d.webFallback)
+          putOpt(map, LinkField.showInterstitial, d.field(LinkField.showInterstitial))
+          putOpt(map, LinkField.isDeepLink, d.field(LinkField.isDeepLink))
+          putOpt(map, LinkField.appleTeamId, d.appleTeamId)
+          putOpt(map, LinkField.iosBundleId, d.iosBundleId)
+          putOpt(map, LinkField.androidPackageName, d.androidPackageName)
+          putOpt(map, LinkField.resolvedPath, d.resolvedPath)
+        }
+        is LinkLookupResult.Failed -> {
+          map.putString("status", "failed")
+          map.putString("error", result.error)
+        }
+      }
+      emitOrBuffer("CliqItLinkLookup", map) { pendingLinkLookup = it }
+    }
+
+    CliqItSDK.onVerify { outcome ->
+      val map = Arguments.createMap()
+      when (outcome) {
+        is VerifyOutcome.Passed -> {
+          map.putString("status", "ok")
+          map.putBoolean("ok", true)
+          putOpt(map, "appId", outcome.result.appId)
+          putOpt(map, "appName", outcome.result.appName)
+          map.putString("message", outcome.result.mismatchMessage)
+          map.putMap("checks", checksMap(outcome.result.checks))
+          map.putString("raw", outcome.result.rawJSON)
+        }
+        is VerifyOutcome.Mismatched -> {
+          map.putString("status", "mismatch")
+          map.putBoolean("ok", false)
+          putOpt(map, "appId", outcome.result.appId)
+          putOpt(map, "appName", outcome.result.appName)
+          map.putString("message", outcome.result.mismatchMessage)
+          map.putMap("checks", checksMap(outcome.result.checks))
+          map.putString("raw", outcome.result.rawJSON)
+        }
+        is VerifyOutcome.Error -> {
+          map.putString("status", "failed")
+          map.putBoolean("ok", false)
+          map.putString("error", outcome.message)
+        }
+      }
+      emitOrBuffer("CliqItVerify", map) { pendingVerify = it }
+    }
+  }
+
+  private fun checksMap(checks: Map<String, com.cliqit.sdk.VerifyCheck>): WritableMap {
+    val out = Arguments.createMap()
+    checks.forEach { (key, check) ->
+      val item = Arguments.createMap()
+      putOpt(item, "actual", check.actual)
+      putOpt(item, "expected", check.expected)
+      item.putBoolean("match", check.match)
+      out.putMap(key, item)
+    }
+    return out
+  }
+
+  private fun emitOrBuffer(
+    event: String,
+    body: WritableMap,
+    buffer: (WritableMap) -> Unit,
+  ) {
+    if (hasListeners) {
+      sendEvent(event, body)
+    } else {
+      buffer(body)
+    }
+  }
+
+  private fun flushPending() {
+    pendingDeepLink?.let {
+      pendingDeepLink = null
+      sendEvent("CliqItDeepLink", it)
+    }
+    pendingDeferredMatch?.let {
+      pendingDeferredMatch = null
+      sendEvent("CliqItDeferredMatch", it)
+    }
+    pendingLinkLookup?.let {
+      pendingLinkLookup = null
+      sendEvent("CliqItLinkLookup", it)
+    }
+    pendingVerify?.let {
+      pendingVerify = null
+      sendEvent("CliqItVerify", it)
+    }
+  }
+
+  private fun sendEvent(event: String, params: WritableMap) {
+    if (!reactContext.hasActiveReactInstance()) return
+    reactContext
+      .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+      .emit(event, params)
+  }
+
+  private fun putOpt(map: WritableMap, key: String, value: String?) {
+    if (value != null) map.putString(key, value) else map.putNull(key)
+  }
+}

package/android/src/main/java/com/cliqit/CliqItPackage.kt

@@ -0,0 +1,14 @@
+package com.cliqit
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class CliqItPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
+    listOf(CliqItModule(reactContext))
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
+    emptyList()
+}

package/android/src/main/java/com/cliqit/sdk/CliqItDefaults.kt

@@ -0,0 +1,17 @@
+package com.cliqit.sdk
+
+object CliqItDefaults {
+  const val SERVER_URL = "https://api.theblockyapp.com"
+  const val DEFERRED_MATCH_PATH = "api/v1/sdk/app/match"
+  const val LINK_LOOKUP_PATH = "api/v1/sdk/link"
+  const val VERIFY_PATH = "api/v1/sdk/verify"
+  const val API_KEY_HEADER = "x-api-key"
+  const val MAX_RETRY = 3
+  const val RETRY_INITIAL_DELAY_MS = 500L
+
+  const val PREFS = "cliqit_sdk"
+  const val KEY_MATCH_REPORTED = "com.cliqit.deferred.match.reported"
+  const val KEY_DEFERRED_DELIVERED = "com.cliqit.deferred.delivered"
+  /** When no explicit domain is configured, only this host + subdomains are accepted. */
+  const val ALLOWED_LINK_DOMAIN = "theblockyapp.com"
+}