@haseeba393/react-native-zendesk 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haseeb Ahmed
+
+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,171 @@
+# react-native-zendesk
+
+React Native Zendesk integration with **New Architecture** support (TurboModules + Fabric component). Use official Zendesk Support SDK UIs on iOS and Android.
+
+## Features
+
+- Initialize Zendesk account config from JavaScript
+- Initialize official Zendesk Support SDK (Android + iOS) when credentials are provided
+- Open Help Center, articles, and contact support in native Zendesk UI (with browser fallback)
+- Embed Help Center in your app with `ZendeskHelpCenterView`
+- Custom fields support for contact requests
+
+## Requirements
+
+- React Native 0.72+ with **New Architecture** enabled
+- iOS 13.0+
+- Android minSdkVersion 21+
+
+## Installation
+
+```bash
+npm install @haseeba393/react-native-zendesk
+# or
+yarn add @haseeba393/react-native-zendesk
+```
+
+### iOS
+
+```bash
+cd ios && pod install
+```
+
+### Android
+
+No additional setup required. Gradle will sync automatically.
+
+## API
+
+```ts
+import {
+  initializeZendesk,
+  getZendeskArticles,
+  getZendeskArticle,
+  searchZendeskArticles,
+  createZendeskTicket,
+  openZendeskHelpCenter,
+  openZendeskArticle,
+  openZendeskContactSupport,
+  openZendeskContactSupportWithDetails,
+  ZendeskHelpCenterView,
+} from '@haseeba393/react-native-zendesk';
+```
+
+### Initialize
+
+```ts
+await initializeZendesk({
+  zendeskUrl: 'https://your-subdomain.zendesk.com', // required for native Zendesk SDK initialization
+  appId: 'zendesk_app_id', // required for native Zendesk SDK initialization
+  clientId: 'zendesk_client_id', // required for native Zendesk SDK initialization
+  // subdomain is optional when zendeskUrl is provided
+  // subdomain: 'your-subdomain',
+  name: 'John Appleseed', // optional identity
+  email: 'agent@example.com', // optional, required for authenticated APIs
+  apiToken: 'zendesk_api_token', // optional, required for authenticated APIs
+  locale: 'en-us',
+});
+```
+
+### Open Help Center
+
+```ts
+await openZendeskHelpCenter();
+```
+
+### Open a specific article
+
+```ts
+await openZendeskArticle(12345);
+```
+
+### Get articles / Search / Create ticket
+
+`getZendeskArticles`, `searchZendeskArticles`, and `createZendeskTicket` open the native Help Center or Contact Support UI. Use `openZendeskHelpCenter` or `openZendeskContactSupport` directly for the same behavior.
+
+### Open contact support
+
+```ts
+await openZendeskContactSupport();
+```
+
+### Open contact support with custom fields
+
+Pass custom fields as key-value pairs. The `key` is the Zendesk custom field ID (as string, e.g. `"360035988993"`), and `value` is the field value.
+
+```ts
+import {
+  openZendeskContactSupportWithDetails,
+  type ZendeskCustomField,
+} from '@haseeba393/react-native-zendesk';
+
+await openZendeskContactSupportWithDetails('user@example.com', [
+  { key: '360035988993', value: '1.0.0' },       // e.g. app version
+  { key: '25024443', value: 'Diagnostic info' }, // e.g. diagnostic description
+]);
+```
+
+### Native Help Center view
+
+```tsx
+<ZendeskHelpCenterView
+  style={{ flex: 1 }}
+  url="https://your-subdomain.zendesk.com/hc/en-us"
+  javaScriptEnabled
+/>
+```
+
+## Behavior Notes
+
+- **New Architecture required**: This package uses TurboModules and Fabric. Ensure `newArchEnabled` is `true` in your React Native config.
+- **Native SDK vs browser**: When `zendeskUrl`, `appId`, and `clientId` are set in `initializeZendesk`, the native Zendesk SDK UIs are used. Otherwise, methods fall back to opening Help Center URLs in the browser.
+- **Subdomain**: Optional if `zendeskUrl` is provided. It is auto-derived from `https://<subdomain>.zendesk.com`.
+- **Custom field IDs**: Find your Zendesk custom field IDs in Admin Center → Objects and rules → Tickets → Fields.
+
+## Example App
+
+An example app is included in `example/` to test this package locally.
+
+```bash
+cd example
+npm install
+cd ios && pod install && cd ..
+npm run ios
+# or
+npm run android
+```
+
+Create `example/zendesk.config.local.ts` with your Zendesk credentials for full testing (see `zendesk.config.local.example.ts`).
+
+## Publishing
+
+Before publishing to npm:
+
+1. Add your name/email to `author` in `package.json`.
+2. Update the `LICENSE` copyright year and holder if needed.
+3. Run `npm pack` to verify the package contents.
+
+### npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+> Scoped packages (`@haseeba393/react-native-zendesk`) require `--access public` for the first publish.
+
+### GitHub
+
+```bash
+git init
+git add .
+git commit -m "Initial release"
+git remote add origin https://github.com/Haseeba393/react-native-zendesk.git
+git push -u origin main
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,55 @@
+buildscript {
+  ext {
+    kotlinVersion = "1.9.24"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.facebook.react"
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "com.rnzendesk"
+  compileSdk safeExtGet("compileSdkVersion", 34)
+
+  defaultConfig {
+    minSdk safeExtGet("minSdkVersion", 24)
+    targetSdk safeExtGet("targetSdkVersion", 34)
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+}
+
+react {
+  jsRootDir = file("../src")
+  libraryName = "RNZendeskSpec"
+  codegenJavaPackageName = "com.rnzendesk"
+}
+
+repositories {
+  maven { url "https://zendesk.jfrog.io/zendesk/repo" }
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
+  implementation "com.squareup.okhttp3:okhttp:4.12.0"
+  implementation "com.zendesk:support:5.5.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest package="com.rnzendesk" />

package/android/src/main/java/com/rnzendesk/ZendeskHelpCenterViewManager.kt

@@ -0,0 +1,38 @@
+package com.rnzendesk
+
+import android.annotation.SuppressLint
+import android.webkit.WebSettings
+import android.webkit.WebView
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.annotations.ReactProp
+
+class ZendeskHelpCenterViewManager : SimpleViewManager<WebView>() {
+  companion object {
+    const val REACT_CLASS = "RNZendeskHelpCenterView"
+  }
+
+  override fun getName(): String = REACT_CLASS
+
+  @SuppressLint("SetJavaScriptEnabled")
+  override fun createViewInstance(reactContext: ThemedReactContext): WebView {
+    return WebView(reactContext).apply {
+      settings.javaScriptEnabled = true
+      settings.domStorageEnabled = true
+      settings.cacheMode = WebSettings.LOAD_DEFAULT
+    }
+  }
+
+  @ReactProp(name = "url")
+  fun setUrl(view: WebView, url: String?) {
+    if (url.isNullOrBlank()) {
+      return
+    }
+    view.loadUrl(url)
+  }
+
+  @ReactProp(name = "javaScriptEnabled", defaultBoolean = true)
+  fun setJavaScriptEnabled(view: WebView, enabled: Boolean) {
+    view.settings.javaScriptEnabled = enabled
+  }
+}

package/android/src/main/java/com/rnzendesk/ZendeskModule.kt

@@ -0,0 +1,341 @@
+package com.rnzendesk
+
+import android.content.Intent
+import android.net.Uri
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.module.annotations.ReactModule
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.IOException
+import java.util.Base64
+import java.util.concurrent.Executors
+import zendesk.core.AnonymousIdentity
+import zendesk.core.Zendesk
+import zendesk.support.CustomField
+import zendesk.support.Support
+import zendesk.support.guide.HelpCenterActivity
+import zendesk.support.guide.ViewArticleActivity
+import zendesk.support.request.RequestActivity
+import zendesk.support.requestlist.RequestListActivity
+
+@ReactModule(name = ZendeskModule.NAME)
+class ZendeskModule(reactContext: ReactApplicationContext) :
+  NativeZendeskSpec(reactContext) {
+
+  companion object {
+    const val NAME = "RNZendesk"
+  }
+
+  private val httpClient = OkHttpClient()
+  private val executor = Executors.newSingleThreadExecutor()
+
+  private var subdomain: String? = null
+  private var email: String? = null
+  private var apiToken: String? = null
+  private var locale: String = ""
+  private var sdkInitialized: Boolean = false
+
+  override fun getName(): String = NAME
+
+  override fun initialize(config: ReadableMap, promise: Promise) {
+    val providedSubdomain = config.getString("subdomain")
+    email = config.getString("email")
+    apiToken = config.getString("apiToken")
+    locale = config.getString("locale") ?: ""
+
+    val zendeskUrl = config.getString("zendeskUrl")
+    val appId = config.getString("appId")
+    val clientId = config.getString("clientId")
+    val name = config.getString("name")
+
+    val derivedSubdomain = extractSubdomainFromZendeskUrl(zendeskUrl)
+    subdomain = if (!providedSubdomain.isNullOrBlank()) {
+      providedSubdomain
+    } else {
+      derivedSubdomain
+    }
+
+    if (subdomain.isNullOrBlank()) {
+      promise.reject(
+        "E_ZENDESK_CONFIG",
+        "Provide subdomain or a valid zendeskUrl (https://<subdomain>.zendesk.com)"
+      )
+      return
+    }
+
+    sdkInitialized = false
+    if (!zendeskUrl.isNullOrBlank() && !appId.isNullOrBlank() && !clientId.isNullOrBlank()) {
+      try {
+        Zendesk.INSTANCE.init(reactApplicationContext, zendeskUrl, appId, clientId)
+        Support.INSTANCE.init(Zendesk.INSTANCE)
+
+        val identityBuilder = AnonymousIdentity.Builder()
+        if (!name.isNullOrBlank()) {
+          identityBuilder.withNameIdentifier(name)
+        }
+        if (!email.isNullOrBlank()) {
+          identityBuilder.withEmailIdentifier(email)
+        }
+        Zendesk.INSTANCE.setIdentity(identityBuilder.build())
+
+        if (locale.isNotBlank()) {
+          Support.INSTANCE.setHelpCenterLocaleOverride(java.util.Locale.forLanguageTag(locale))
+        }
+        sdkInitialized = true
+      } catch (error: Exception) {
+        promise.reject("E_ZENDESK_SDK_INIT", error.message, error)
+        return
+      }
+    }
+    promise.resolve(true)
+  }
+
+  override fun getArticles(
+    locale: String?,
+    labels: ReadableArray?,
+    page: Double?,
+    perPage: Double?,
+    promise: Promise
+  ) {
+    // Use native Help Center UI instead of REST APIs.
+    openHelpCenter(promise)
+  }
+
+  override fun getArticle(articleId: Double, locale: String?, promise: Promise) {
+    // Use native article UI instead of REST APIs.
+    openArticle(articleId, promise)
+  }
+
+  override fun searchArticles(
+    query: String,
+    locale: String?,
+    page: Double?,
+    perPage: Double?,
+    promise: Promise
+  ) {
+    // Search is handled by native Help Center UI.
+    openHelpCenter(promise)
+  }
+
+  override fun createTicket(request: ReadableMap, promise: Promise) {
+    // Use native contact support UI instead of REST ticket APIs.
+    openContactSupport(promise)
+  }
+
+  override fun openHelpCenter(promise: Promise) {
+    val domain = requireSubdomain(promise) ?: return
+    val activity = currentActivity
+    if (sdkInitialized && activity != null) {
+      try {
+        HelpCenterActivity.builder().show(activity)
+        promise.resolve(true)
+      } catch (error: Exception) {
+        promise.reject("E_ZENDESK_OPEN_HELP_CENTER", error.message, error)
+      }
+      return
+    }
+    val localeSegment = if (locale.isNotBlank()) "/$locale" else ""
+    openUrl("https://$domain.zendesk.com/hc$localeSegment", promise)
+  }
+
+  override fun openArticle(articleId: Double, promise: Promise) {
+    val domain = requireSubdomain(promise) ?: return
+    val id = articleId.toLong()
+    val activity = currentActivity
+    if (sdkInitialized && activity != null) {
+      try {
+        ViewArticleActivity.builder(id).show(activity)
+        promise.resolve(true)
+      } catch (error: Exception) {
+        promise.reject("E_ZENDESK_OPEN_ARTICLE", error.message, error)
+      }
+      return
+    }
+    openUrl("https://$domain.zendesk.com/hc/articles/$id", promise)
+  }
+
+  override fun openContactSupport(promise: Promise) {
+    val domain = requireSubdomain(promise) ?: return
+    val activity = currentActivity
+    if (sdkInitialized && activity != null) {
+      try {
+        RequestListActivity.builder().show(activity)
+        promise.resolve(true)
+      } catch (error: Exception) {
+        promise.reject("E_ZENDESK_OPEN_CONTACT_SUPPORT", error.message, error)
+      }
+      return
+    }
+    val localeSegment = if (locale.isNotBlank()) "/$locale" else ""
+    openUrl("https://$domain.zendesk.com/hc$localeSegment/requests/new", promise)
+  }
+
+  override fun openContactSupportWithDetails(
+    email: String,
+    customFields: ReadableArray,
+    promise: Promise
+  ) {
+    val domain = requireSubdomain(promise) ?: return
+    val activity = currentActivity
+
+    if (sdkInitialized && activity != null) {
+      try {
+        if (email.isNotBlank()) {
+          val identity = AnonymousIdentity.Builder()
+            .withEmailIdentifier(email)
+            .build()
+          Zendesk.INSTANCE.setIdentity(identity)
+        }
+
+        val fields = arrayListOf<CustomField>()
+        for (i in 0 until customFields.size()) {
+          val item = customFields.getMap(i)
+          val key = item.getString("key") ?: continue
+          val value = item.getString("value") ?: continue
+          val fieldId = key.trim().removeSuffix("L").toLongOrNull() ?: continue
+          fields.add(CustomField(fieldId, value))
+        }
+
+        RequestActivity.builder()
+          .withCustomFields(fields)
+          .show(activity)
+        promise.resolve(true)
+      } catch (error: Exception) {
+        promise.reject("E_ZENDESK_OPEN_CONTACT_SUPPORT", error.message, error)
+      }
+      return
+    }
+
+    val localeSegment = if (locale.isNotBlank()) "/$locale" else ""
+    openUrl("https://$domain.zendesk.com/hc$localeSegment/requests/new", promise)
+  }
+
+  private fun openUrl(url: String, promise: Promise) {
+    try {
+      val activity = currentActivity
+      if (activity == null) {
+        promise.reject("E_ZENDESK_ACTIVITY", "No active activity available")
+        return
+      }
+
+      val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
+      activity.startActivity(intent)
+      promise.resolve(true)
+    } catch (error: Exception) {
+      promise.reject("E_ZENDESK_OPEN_URL", error.message, error)
+    }
+  }
+
+  private fun request(method: String, url: String, payload: String?, promise: Promise) {
+    executor.execute {
+      try {
+        val requestBuilder = Request.Builder().url(url)
+        authHeader()?.let { requestBuilder.addHeader("Authorization", it) }
+        requestBuilder.addHeader("Accept", "application/json")
+
+        if (method == "POST") {
+          val body = (payload ?: "{}").toRequestBody("application/json".toMediaType())
+          requestBuilder.post(body)
+        } else {
+          requestBuilder.get()
+        }
+
+        httpClient.newCall(requestBuilder.build()).execute().use { response ->
+          val body = response.body?.string() ?: "{}"
+          if (!response.isSuccessful) {
+            promise.reject(
+              "E_ZENDESK_HTTP",
+              "Zendesk request failed (${response.code}): $body"
+            )
+            return@use
+          }
+
+          val json = JSONObject(body)
+          val map = Arguments.makeNativeMap(json.toMap())
+          promise.resolve(map)
+        }
+      } catch (error: IOException) {
+        promise.reject("E_ZENDESK_NETWORK", error.message, error)
+      } catch (error: Exception) {
+        promise.reject("E_ZENDESK_UNKNOWN", error.message, error)
+      }
+    }
+  }
+
+  private fun JSONObject.toMap(): MutableMap<String, Any?> {
+    val map = mutableMapOf<String, Any?>()
+    keys().forEach { key ->
+      map[key] = when (val value = get(key)) {
+        is JSONArray -> value.toList()
+        is JSONObject -> value.toMap()
+        JSONObject.NULL -> null
+        else -> value
+      }
+    }
+    return map
+  }
+
+  private fun JSONArray.toList(): List<Any?> {
+    val list = mutableListOf<Any?>()
+    for (index in 0 until length()) {
+      val value = get(index)
+      list.add(
+        when (value) {
+          is JSONArray -> value.toList()
+          is JSONObject -> value.toMap()
+          JSONObject.NULL -> null
+          else -> value
+        }
+      )
+    }
+    return list
+  }
+
+  private fun configuredApiBaseUrl(promise: Promise): String? {
+    val domain = requireSubdomain(promise) ?: return null
+    return "https://$domain.zendesk.com/api/v2"
+  }
+
+  private fun effectiveLocale(requestedLocale: String?): String = requestedLocale ?: locale
+
+  private fun authHeader(): String? {
+    if (email.isNullOrBlank() || apiToken.isNullOrBlank()) {
+      return null
+    }
+    val token = "${email}/token:$apiToken"
+    val encoded = Base64.getEncoder().encodeToString(token.toByteArray(Charsets.UTF_8))
+    return "Basic $encoded"
+  }
+
+  private fun requireSubdomain(promise: Promise): String? {
+    val domain = subdomain
+    if (domain.isNullOrBlank()) {
+      promise.reject("E_ZENDESK_CONFIG", "Zendesk is not initialized. Call initialize() first.")
+      return null
+    }
+    return domain
+  }
+
+  private fun extractSubdomainFromZendeskUrl(zendeskUrl: String?): String? {
+    if (zendeskUrl.isNullOrBlank()) {
+      return null
+    }
+    return try {
+      val host = Uri.parse(zendeskUrl).host ?: return null
+      if (!host.endsWith(".zendesk.com")) {
+        return null
+      }
+      host.substringBefore(".zendesk.com").takeIf { it.isNotBlank() }
+    } catch (_: Exception) {
+      null
+    }
+  }
+}

package/android/src/main/java/com/rnzendesk/ZendeskPackage.kt

@@ -0,0 +1,59 @@
+package com.rnzendesk
+
+import com.facebook.react.TurboReactPackage
+import com.facebook.react.ViewManagerOnDemandReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+
+class ZendeskPackage :
+  TurboReactPackage(),
+  ViewManagerOnDemandReactPackage {
+
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == ZendeskModule.NAME) {
+      ZendeskModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+    return ReactModuleInfoProvider {
+      mapOf(
+        ZendeskModule.NAME to ReactModuleInfo(
+          ZendeskModule.NAME,
+          ZendeskModule::class.java.name,
+          false,
+          false,
+          true,
+          false,
+          true
+        )
+      )
+    }
+  }
+
+  override fun createViewManagers(
+    reactContext: ReactApplicationContext
+  ): List<ViewManager<*, *>> {
+    return listOf(ZendeskHelpCenterViewManager())
+  }
+
+  override fun getViewManagerNames(reactContext: ReactApplicationContext): MutableList<String> {
+    return mutableListOf(ZendeskHelpCenterViewManager.REACT_CLASS)
+  }
+
+  override fun createViewManager(
+    reactContext: ReactApplicationContext,
+    viewManagerName: String
+  ): ViewManager<*, *>? {
+    return if (viewManagerName == ZendeskHelpCenterViewManager.REACT_CLASS) {
+      ZendeskHelpCenterViewManager()
+    } else {
+      null
+    }
+  }
+}

package/ios/RNZendeskHelpCenterView.h

@@ -0,0 +1,9 @@
+#import <UIKit/UIKit.h>
+#import <WebKit/WebKit.h>
+
+@interface RNZendeskHelpCenterView : UIView
+
+@property(nonatomic, copy) NSString *url;
+@property(nonatomic, assign) BOOL javaScriptEnabled;
+
+@end