react-native-newinstance-chat 0.2.0 → 0.3.0

package/NewinstanceChat.podspec

@@ -18,7 +18,7 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = { "DEFINES_MODULE" => "YES" }
 
   # Native chat SDK we wrap, published on CocoaPods Trunk.
-  s.dependency "LiveAndAiChat", "~> 0.2.0"
+  s.dependency "LiveAndAiChat", "~> 0.3.0"
 
   install_modules_dependencies(s)
 end

package/README.md

@@ -75,6 +75,96 @@ sdk.openChat();
 The chat screen renders natively — there is no React component to mount.
 Your RN UI is whatever button / banner / FAB triggers `openChat()`.
 
+### Authenticating the customer
+
+`apiKey` is the publishable widget key **ID**, never the `keyId:secret`
+form, which belongs on your server only.
+
+There are two ways to say who the customer is.
+
+**Anonymous.** Supply nothing. The chat collects whatever it needs.
+
+**Verified.** Have your backend mint a chat identity token and hand it to
+the app. The token is the identity, so no other customer fields are needed:
+
+```ts
+// Your backend, with the SECRET key, typically at sign-in:
+//   POST https://api.newinstance.cloud/api/v1/chat/sessions
+//   x-api-key: sk_live_abc123:YOUR_SECRET_KEY
+//   { "customerId": "usr_123", "customerName": "Ada Lovelace",
+//     "customerEmail": "ada@example.com", "customerPhone": "+44 20 7946 0958",
+//     "metadata": { "plan": "enterprise" }, "expiresInSeconds": 21600 }
+//   -> { token, expiresAt, session: { sessionId, ... } }
+
+sdk.setUserToken(tokenFromYourBackend);
+```
+
+Everything you put in that payload is signed into the token, so the chat
+session already knows the customer before the app says anything:
+
+```
+customerId    -> the verified customer id
+customerName  -> the name on the conversation and on every message
+customerEmail -> also satisfies the merchant's "require email" setting
+customerPhone -> shown to the agent
+metadata      -> any extra context your agents should see
+```
+
+The client then passes **one string**. It never repeats the name, never
+repeats the email, and is never shown a pre-chat form.
+
+The server verifies the signature and derives the name, email and customer
+id from the token's claims, so a tampered app cannot claim to be someone
+else. `customerId` passed *without* a token is recorded for agent context
+only and is not treated as identity.
+
+Tokens expire (one hour by default). A rejected token arrives on the error
+event as `INVALID_IDENTITY_TOKEN`; mint a fresh one.
+
+Sessions are managed over REST: `POST /api/v1/chat/sessions` to create,
+`DELETE /api/v1/chat/sessions?customerId=...` on sign-out. You choose the
+lifetime (60 seconds to 24 hours, default 1 hour) with `expiresInSeconds`.
+
+A customer holds **one** live session at a time. Creating another while
+theirs is valid returns `409` with the existing session; mint again once it
+expires or after you revoke it. Revocation takes effect on the next request,
+so an invalidated token stops working immediately even though its signature
+is still valid.
+
+The token is the session: the identity is signed into it, and the platform
+stores no copy. Decode the token if you need the name, email, phone or
+metadata back.
+
+
+### Theming
+
+The chat resolves colours from three layers:
+
+```
+dashboard theme  >  your local theme  >  the SDK's built-in theme
+```
+
+The merchant's dashboard configuration wins, your local theme fills in what
+the dashboard did not set, and the built-in palette fills in the rest, so
+every colour always has a value, even with no network. Merging is per
+token, so setting one colour does not discard the others.
+
+```ts
+const sdk = new NewinstanceChat({
+  apiKey: 'sk_live_…',
+  theme: { mode: 'dark', sentBubble: '#16A34A' },
+});
+```
+
+Every `ChatThemeOverride` field is optional; colours are hex strings. An
+unparseable value is ignored rather than throwing. `mode` is only a
+preference: the dashboard's explicit light/dark wins, and its `auto` defers
+to yours, then to the device.
+
+If remote configuration cannot be fetched, your local theme still applies
+and the chat stays fully usable; you get a `CONFIG_FETCH_FAILED` warning on
+the error event.
+
 ### Subscribing to events
 
 ```ts
@@ -89,6 +179,39 @@ Event names: `messageReceived`, `messageSent`, `agentTypingChanged`,
 `connectionStateChanged`, `unreadCountChanged`, `error`,
 `attachmentUpdated`, `chatClosed`. See `src/types.ts` for payload shapes.
 
+### The error event
+
+`error` is the channel for "why is my chat not working". It never surfaces
+in the chat interface the customer sees, and it never carries the API key,
+the identity token, or customer data.
+
+```ts
+sdk.addListener('error', (e) => {
+  if (e.code === 'INVALID_IDENTITY_TOKEN') return refreshChatToken();
+  if (!e.recoverable) reportToYourMonitoring(e.code, e.message);
+});
+```
+
+| `code` | What went wrong |
+|---|---|
+| `MISSING_WIDGET_KEY` | No API key was supplied |
+| `INVALID_PUBLIC_KEY` | The key was rejected: wrong key, wrong environment, revoked, expired |
+| `CHAT_CONFIG_UNAVAILABLE` | The key is fine, but the organization has no chat configuration |
+| `CHAT_DISABLED` | Chat is switched off in the dashboard |
+| `CONFIG_FETCH_FAILED` | Remote configuration could not be loaded; the local/built-in theme is in use |
+| `INVALID_IDENTITY_TOKEN` | The token was malformed, expired, or signed for another organization |
+| `NETWORK_ERROR` | The backend could not be reached |
+| `TRANSPORT_ERROR` | The realtime connection dropped |
+| `CHAT_INITIALIZATION_FAILED` | The conversation could not be started |
+| `MESSAGE_SEND_FAILED` | A message could not be delivered |
+| `ATTACHMENT_FAILED` | An attachment could not be uploaded |
+| `SERVER_ERROR` | The backend returned something unusable |
+
+The same codes are emitted by the web, Android, iOS and Flutter SDKs.
+`type` (`network` / `validation` / `auth` / `system`) is still present for
+handlers written against 0.2.x; `code` is `undefined` only when the
+underlying native SDK predates coded errors.
+
 ### The chat-close event
 
 `chatClosed` fires **exactly once per chat presentation**, however the

package/android/build.gradle

@@ -73,5 +73,5 @@ repositories {
 dependencies {
   implementation "com.facebook.react:react-android"
   // Native chat SDK the bridge wraps. Published under cloud.newinstance.
-  implementation "cloud.newinstance:liveandaichat:0.2.0"
+  implementation "cloud.newinstance:liveandaichat:0.3.0"
 }

package/android/src/main/java/com/newinstancechat/NewinstanceChatModule.kt

@@ -4,7 +4,10 @@ import cloud.newinstance.liveandaichat.ConnectionState
 import cloud.newinstance.liveandaichat.LiveAndAiChat
 import cloud.newinstance.liveandaichat.LiveAndAiChatConfig
 import cloud.newinstance.liveandaichat.LiveAndAiChatError
+import cloud.newinstance.liveandaichat.ChatSdkError
+import cloud.newinstance.liveandaichat.ChatThemeOverride
 import cloud.newinstance.liveandaichat.ChatUser
+import cloud.newinstance.liveandaichat.ErrorType
 import cloud.newinstance.liveandaichat.model.AttachmentRequest
 import cloud.newinstance.liveandaichat.model.AttachmentSource
 import cloud.newinstance.liveandaichat.model.ChatCloseEvent
@@ -15,6 +18,7 @@ import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.DeviceEventManagerModule
 
@@ -39,6 +43,13 @@ class NewinstanceChatModule(reactContext: ReactApplicationContext) :
   private var sdk: LiveAndAiChat? = null
   private var pendingUser: ChatUser? = null
 
+  /**
+   * Whether the host identified the customer with a chat identity token.
+   * Used only to tell an API-key rejection apart from a token rejection when
+   * reporting an auth failure.
+   */
+  private var usingIdentityToken: Boolean = false
+
   override fun getName(): String = NAME
 
   private fun emit(event: String, body: Any?) {
@@ -66,12 +77,27 @@ class NewinstanceChatModule(reactContext: ReactApplicationContext) :
       }
     } else null
 
+    // Local theme arrives as a flat string map; unknown keys are ignored by
+    // ChatThemeOverride.fromMap so a newer JS SDK cannot break this bridge.
+    val themeOverride = if (config.hasKey("theme")) {
+      config.getMap("theme")?.let { map ->
+        val values = mutableMapOf<String, String?>()
+        val it = map.keySetIterator()
+        while (it.hasNextKey()) {
+          val key = it.nextKey()
+          if (map.getType(key) == ReadableType.String) values[key] = map.getString(key)
+        }
+        ChatThemeOverride.fromMap(values)
+      }
+    } else null
+
     try {
       val cfg = LiveAndAiChatConfig(
         apiKey = apiKey,
         baseUrl = baseUrl ?: LiveAndAiChatConfig.DEFAULT_BASE_URL,
         transport = transport,
         initialMessage = initialMessage,
+        theme = themeOverride,
       )
       sdk?.destroy()
       val builder = LiveAndAiChat.Builder(reactApplicationContext).config(cfg)
@@ -87,13 +113,18 @@ class NewinstanceChatModule(reactContext: ReactApplicationContext) :
   }
 
   override fun setUser(user: ReadableMap) {
-    val name = user.getString("customerName") ?: return
-    if (name.isBlank()) return
+    val token = if (user.hasKey("customerToken")) user.getString("customerToken") else null
+    // With a token the display name is irrelevant: the backend replaces the
+    // whole identity from the token's signed claims.
+    val name = user.getString("customerName")?.takeIf { it.isNotBlank() }
+      ?: (if (!token.isNullOrBlank()) "Customer" else return)
     val chatUser = ChatUser(
       customerName = name,
       customerId = if (user.hasKey("customerId")) user.getString("customerId") else null,
       customerEmail = if (user.hasKey("customerEmail")) user.getString("customerEmail") else null,
+      customerToken = token,
     )
+    usingIdentityToken = !token.isNullOrBlank()
     val current = sdk
     if (current != null) {
       current.setUser(chatUser)
@@ -240,12 +271,46 @@ class NewinstanceChatModule(reactContext: ReactApplicationContext) :
 
   override fun onError(error: LiveAndAiChatError) {
     val map = Arguments.createMap()
+    map.putString("code", sdkErrorCode(error))
     map.putString("type", error.type.name.lowercase())
     map.putString("message", error.message)
     map.putBoolean("recoverable", error.recoverable)
     emit("error", map)
   }
 
+  /**
+   * Normalise onto the cross-platform code vocabulary. `error.code` carries
+   * the raw GraphQL/transport code when the native SDK has one; otherwise the
+   * broad type decides. An auth failure while a chat identity token is in use
+   * is reported as a token problem, which is the difference between
+   * "rotate your key" and "mint a fresh token".
+   */
+  private fun sdkErrorCode(error: LiveAndAiChatError): String {
+    val known = setOf(
+      ChatSdkError.CHAT_CONFIG_UNAVAILABLE,
+      ChatSdkError.CHAT_DISABLED,
+      ChatSdkError.INVALID_PUBLIC_KEY,
+      ChatSdkError.MISSING_WIDGET_KEY,
+      ChatSdkError.CONFIG_FETCH_FAILED,
+      ChatSdkError.CHAT_INITIALIZATION_FAILED,
+      ChatSdkError.NETWORK_ERROR,
+      ChatSdkError.SERVER_ERROR,
+      ChatSdkError.INVALID_IDENTITY_TOKEN,
+      ChatSdkError.TRANSPORT_ERROR,
+      ChatSdkError.MESSAGE_SEND_FAILED,
+      ChatSdkError.ATTACHMENT_FAILED,
+    )
+    error.code?.let { if (it in known) return it }
+    return when (error.type) {
+      ErrorType.AUTH ->
+        if (usingIdentityToken) ChatSdkError.INVALID_IDENTITY_TOKEN else ChatSdkError.INVALID_PUBLIC_KEY
+      ErrorType.UNAVAILABLE -> ChatSdkError.CHAT_CONFIG_UNAVAILABLE
+      ErrorType.NETWORK -> ChatSdkError.NETWORK_ERROR
+      ErrorType.VALIDATION -> ChatSdkError.SERVER_ERROR
+      ErrorType.SYSTEM -> ChatSdkError.CHAT_INITIALIZATION_FAILED
+    }
+  }
+
   // MARK: - Helpers
 
   private fun chatMessageToMap(m: ChatMessage): WritableMap {

package/ios/NewinstanceChatImpl.swift

@@ -29,6 +29,11 @@ public final class NewinstanceChatImpl: NSObject, LiveAndAiChatDelegate {
   private var sdk: LiveAndAiChat?
   private var pendingUser: ChatUser?
 
+  /// Whether the host identified the customer with a chat identity token.
+  /// Used only to tell an API-key rejection apart from a token rejection when
+  /// reporting an auth failure.
+  private var usingIdentityToken: Bool = false
+
   // MARK: - configure / setUser / initialize
 
   @objc(configure:resolver:rejecter:)
@@ -49,6 +54,17 @@ public final class NewinstanceChatImpl: NSObject, LiveAndAiChatDelegate {
       }
     }()
 
+    // Local theme arrives as a flat string dictionary; unknown keys are
+    // ignored by fromDictionary so a newer JS SDK cannot break this bridge.
+    let themeOverride: ChatThemeOverride? = {
+      guard let raw = configDict["theme"] as? NSDictionary else { return nil }
+      var values: [String: String] = [:]
+      for (key, value) in raw {
+        if let k = key as? String, let v = value as? String { values[k] = v }
+      }
+      return values.isEmpty ? nil : ChatThemeOverride.fromDictionary(values)
+    }()
+
     DispatchQueue.main.async { [weak self] in
       guard let self = self else { return }
       do {
@@ -56,7 +72,8 @@ public final class NewinstanceChatImpl: NSObject, LiveAndAiChatDelegate {
           apiKey: apiKey,
           baseUrl: baseUrl ?? LiveAndAiChatConfig.defaultBaseUrl,
           transport: transport,
-          initialMessage: initialMessage
+          initialMessage: initialMessage,
+          theme: themeOverride
         )
         let builder = LiveAndAiChat.Builder().config(cfg)
         if let user = self.pendingUser { _ = builder.user(user) }
@@ -76,14 +93,20 @@ public final class NewinstanceChatImpl: NSObject, LiveAndAiChatDelegate {
 
   @objc(setUser:)
   public func setUser(_ userDict: NSDictionary) {
-    guard let name = userDict["customerName"] as? String, !name.isEmpty else { return }
+    let token = (userDict["customerToken"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+    // With a token the display name is irrelevant: the backend replaces the
+    // whole identity from the token's signed claims.
+    let providedName = (userDict["customerName"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+    guard let name = providedName ?? (token != nil ? "Customer" : nil) else { return }
     let user = ChatUser(
       customerName: name,
       customerId: userDict["customerId"] as? String,
-      customerEmail: userDict["customerEmail"] as? String
+      customerEmail: userDict["customerEmail"] as? String,
+      customerToken: token
     )
     DispatchQueue.main.async { [weak self] in
       guard let self = self else { return }
+      self.usingIdentityToken = token != nil
       if let sdk = self.sdk {
         sdk.setUser(user)
       } else {
@@ -247,6 +270,7 @@ public final class NewinstanceChatImpl: NSObject, LiveAndAiChatDelegate {
   }
   public func didEncounterError(_ error: LiveAndAiChatError) {
     emitter?.emitEvent("error", body: [
+      "code": error.sdkCode(usingIdentityToken: usingIdentityToken),
       "type": Self.errorTypeName(error.type),
       "message": error.message,
       "recoverable": error.recoverable,

package/lib/module/index.js

@@ -29,11 +29,27 @@ export class NewinstanceChat {
    * Identify the customer. Safe to call before or after `initialize()`. If
    * called before `configure()` resolves, the user is queued and applied
    * once the native instance exists.
+   *
+   * Prefer `customerToken`: it is minted by your backend, so the server can
+   * verify who the customer is. `customerName` / `customerEmail` /
+   * `customerId` alone are client-asserted and are not trusted as identity.
    */
   setUser(user) {
     NativeNewinstanceChat.setUser(user);
   }
 
+  /**
+   * Identify the customer with a backend-minted chat identity token only.
+   * Nothing else needs to be supplied: the server derives the name, email and
+   * customer id from the token's signed claims.
+   */
+  setUserToken(customerToken) {
+    NativeNewinstanceChat.setUser({
+      customerName: 'Customer',
+      customerToken
+    });
+  }
+
   /**
    * Fetch org config, restore the saved conversation, and connect the
    * subscription transport in the background. Concurrent callers share

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["NativeEventEmitter","NativeModules","NativeNewinstanceChat","emitterSource","NewinstanceChat","emitter","constructor","config","ready","configure","setUser","user","initialize","openChat","closeChat","sendMessage","text","retryMessage","messageId","attachFile","opts","source","uri","Promise","reject","Error","removeAttachment","id","clearAttachments","addListener","event","handler","sub","remove","destroy"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,SACEA,kBAAkB,EAClBC,aAAa,QAER,cAAc;AAErB,OAAOC,qBAAqB,MAAM,4BAAyB;AAqB3D;AACA;AACA;AACA,MAAMC,aAAkB,GACtBF,aAAa,CAACG,eAAe,IAAKF,qBAAiC;AACrE,MAAMG,OAAO,GAAG,IAAIL,kBAAkB,CAACG,aAAa,CAAC;;AAErD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,CAAC;EAC3B;;EAGAE,WAAWA,CAACC,MAA6B,EAAE;IACzC,IAAI,CAACC,KAAK,GAAGN,qBAAqB,CAACO,SAAS,CAACF,MAAM,CAAC;EACtD;;EAEA;AACF;AACA;AACA;AACA;EACEG,OAAOA,CAACC,IAAc,EAAQ;IAC5BT,qBAAqB,CAACQ,OAAO,CAACC,IAAI,CAAC;EACrC;;EAEA;AACF;AACA;AACA;AACA;EACEC,UAAUA,CAAA,EAAkB;IAC1B,OAAOV,qBAAqB,CAACU,UAAU,CAAC,CAAC;EAC3C;;EAEA;EACAC,QAAQA,CAAA,EAAS;IACfX,qBAAqB,CAACW,QAAQ,CAAC,CAAC;EAClC;;EAEA;EACAC,SAASA,CAAA,EAAS;IAChBZ,qBAAqB,CAACY,SAAS,CAAC,CAAC;EACnC;EAEAC,WAAWA,CAACC,IAAY,EAAQ;IAC9Bd,qBAAqB,CAACa,WAAW,CAACC,IAAI,CAAC;EACzC;EAEAC,YAAYA,CAACC,SAAiB,EAAQ;IACpChB,qBAAqB,CAACe,YAAY,CAACC,SAAS,CAAC;EAC/C;;EAEA;AACF;AACA;AACA;AACA;EACEC,UAAUA,CAACC,IAAqB,EAAmB;IACjD,IAAI,CAACA,IAAI,CAACC,MAAM,IAAI,CAACD,IAAI,CAACE,GAAG,EAAE;MAC7B,OAAOC,OAAO,CAACC,MAAM,CAAC,IAAIC,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxF;IACA,OAAOvB,qBAAqB,CAACiB,UAAU,CAACC,IAAI,CAAC;EAC/C;;EAEA;EACAM,gBAAgBA,CAACC,EAAU,EAAQ;IACjCzB,qBAAqB,CAACwB,gBAAgB,CAACC,EAAE,CAAC;EAC5C;;EAEA;EACAC,gBAAgBA,CAAA,EAAS;IACvB1B,qBAAqB,CAAC0B,gBAAgB,CAAC,CAAC;EAC1C;;EAEA;AACF;AACA;AACA;EACEC,WAAWA,CACTC,KAAQ,EACRC,OAAwB,EACZ;IACZ,MAAMC,GAAwB,GAAG3B,OAAO,CAACwB,WAAW,CAClDC,KAAK,EACLC,OACF,CAAC;IACD,OAAO,MAAMC,GAAG,CAACC,MAAM,CAAC,CAAC;EAC3B;;EAEA;AACF;AACA;AACA;EACEC,OAAOA,CAAA,EAAS;IACdhC,qBAAqB,CAACgC,OAAO,CAAC,CAAC;EACjC;AACF","ignoreList":[]}
+{"version":3,"names":["NativeEventEmitter","NativeModules","NativeNewinstanceChat","emitterSource","NewinstanceChat","emitter","constructor","config","ready","configure","setUser","user","setUserToken","customerToken","customerName","initialize","openChat","closeChat","sendMessage","text","retryMessage","messageId","attachFile","opts","source","uri","Promise","reject","Error","removeAttachment","id","clearAttachments","addListener","event","handler","sub","remove","destroy"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,SACEA,kBAAkB,EAClBC,aAAa,QAER,cAAc;AAErB,OAAOC,qBAAqB,MAAM,4BAAyB;AAyB3D;AACA;AACA;AACA,MAAMC,aAAkB,GACtBF,aAAa,CAACG,eAAe,IAAKF,qBAAiC;AACrE,MAAMG,OAAO,GAAG,IAAIL,kBAAkB,CAACG,aAAa,CAAC;;AAErD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,CAAC;EAC3B;;EAGAE,WAAWA,CAACC,MAA6B,EAAE;IACzC,IAAI,CAACC,KAAK,GAAGN,qBAAqB,CAACO,SAAS,CAACF,MAAM,CAAC;EACtD;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACEG,OAAOA,CAACC,IAAc,EAAQ;IAC5BT,qBAAqB,CAACQ,OAAO,CAACC,IAAI,CAAC;EACrC;;EAEA;AACF;AACA;AACA;AACA;EACEC,YAAYA,CAACC,aAAqB,EAAQ;IACxCX,qBAAqB,CAACQ,OAAO,CAAC;MAAEI,YAAY,EAAE,UAAU;MAAED;IAAc,CAAC,CAAC;EAC5E;;EAEA;AACF;AACA;AACA;AACA;EACEE,UAAUA,CAAA,EAAkB;IAC1B,OAAOb,qBAAqB,CAACa,UAAU,CAAC,CAAC;EAC3C;;EAEA;EACAC,QAAQA,CAAA,EAAS;IACfd,qBAAqB,CAACc,QAAQ,CAAC,CAAC;EAClC;;EAEA;EACAC,SAASA,CAAA,EAAS;IAChBf,qBAAqB,CAACe,SAAS,CAAC,CAAC;EACnC;EAEAC,WAAWA,CAACC,IAAY,EAAQ;IAC9BjB,qBAAqB,CAACgB,WAAW,CAACC,IAAI,CAAC;EACzC;EAEAC,YAAYA,CAACC,SAAiB,EAAQ;IACpCnB,qBAAqB,CAACkB,YAAY,CAACC,SAAS,CAAC;EAC/C;;EAEA;AACF;AACA;AACA;AACA;EACEC,UAAUA,CAACC,IAAqB,EAAmB;IACjD,IAAI,CAACA,IAAI,CAACC,MAAM,IAAI,CAACD,IAAI,CAACE,GAAG,EAAE;MAC7B,OAAOC,OAAO,CAACC,MAAM,CAAC,IAAIC,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxF;IACA,OAAO1B,qBAAqB,CAACoB,UAAU,CAACC,IAAI,CAAC;EAC/C;;EAEA;EACAM,gBAAgBA,CAACC,EAAU,EAAQ;IACjC5B,qBAAqB,CAAC2B,gBAAgB,CAACC,EAAE,CAAC;EAC5C;;EAEA;EACAC,gBAAgBA,CAAA,EAAS;IACvB7B,qBAAqB,CAAC6B,gBAAgB,CAAC,CAAC;EAC1C;;EAEA;AACF;AACA;AACA;EACEC,WAAWA,CACTC,KAAQ,EACRC,OAAwB,EACZ;IACZ,MAAMC,GAAwB,GAAG9B,OAAO,CAAC2B,WAAW,CAClDC,KAAK,EACLC,OACF,CAAC;IACD,OAAO,MAAMC,GAAG,CAACC,MAAM,CAAC,CAAC;EAC3B;;EAEA;AACF;AACA;AACA;EACEC,OAAOA,CAAA,EAAS;IACdnC,qBAAqB,CAACmC,OAAO,CAAC,CAAC;EACjC;AACF","ignoreList":[]}

package/lib/typescript/src/index.d.ts

@@ -1,5 +1,5 @@
 import type { AttachmentInput, ChatUser, EventHandler, EventName, NewinstanceChatConfig } from './types';
-export type { AttachmentInput, ChatMessage, ChatUser, ConnectionState, EventMap, EventName, NewinstanceChatConfig, NewinstanceChatError, NewinstanceChatErrorType, } from './types';
+export type { AttachmentInput, AttachmentUpdate, ChatClosedEvent, ChatMessage, ChatThemeOverride, ChatUser, ConnectionState, EventMap, EventName, NewinstanceChatConfig, NewinstanceChatError, NewinstanceChatErrorCode, NewinstanceChatErrorType, } from './types';
 /**
  * React Native binding for the native LiveAndAiChat iOS / Android SDKs.
  *
@@ -18,8 +18,18 @@ export declare class NewinstanceChat {
      * Identify the customer. Safe to call before or after `initialize()`. If
      * called before `configure()` resolves, the user is queued and applied
      * once the native instance exists.
+     *
+     * Prefer `customerToken`: it is minted by your backend, so the server can
+     * verify who the customer is. `customerName` / `customerEmail` /
+     * `customerId` alone are client-asserted and are not trusted as identity.
      */
     setUser(user: ChatUser): void;
+    /**
+     * Identify the customer with a backend-minted chat identity token only.
+     * Nothing else needs to be supplied: the server derives the name, email and
+     * customer id from the token's signed claims.
+     */
+    setUserToken(customerToken: string): void;
     /**
      * Fetch org config, restore the saved conversation, and connect the
      * subscription transport in the background. Concurrent callers share

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,eAAe,EACf,WAAW,EACX,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,SAAS,EACT,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,SAAS,CAAC;AASjB;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;gBAElB,MAAM,EAAE,qBAAqB;IAIzC;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAI7B;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,uEAAuE;IACvE,QAAQ,IAAI,IAAI;IAIhB,sCAAsC;IACtC,SAAS,IAAI,IAAI;IAIjB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/B,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAOlD,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIlC,mEAAmE;IACnE,gBAAgB,IAAI,IAAI;IAIxB;;;OAGG;IACH,WAAW,CAAC,CAAC,SAAS,SAAS,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GACvB,MAAM,IAAI;IAQb;;;OAGG;IACH,OAAO,IAAI,IAAI;CAGhB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,SAAS,EACT,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,SAAS,CAAC;AASjB;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;gBAElB,MAAM,EAAE,qBAAqB;IAIzC;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAI7B;;;;OAIG;IACH,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAIzC;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,uEAAuE;IACvE,QAAQ,IAAI,IAAI;IAIhB,sCAAsC;IACtC,SAAS,IAAI,IAAI;IAIjB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/B,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAOlD,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIlC,mEAAmE;IACnE,gBAAgB,IAAI,IAAI;IAIxB;;;OAGG;IACH,WAAW,CAAC,CAAC,SAAS,SAAS,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GACvB,MAAM,IAAI;IAQb;;;OAGG;IACH,OAAO,IAAI,IAAI;CAGhB"}

package/lib/typescript/src/types.d.ts

@@ -14,11 +14,66 @@ export interface NewinstanceChatConfig {
     transport?: 'sse' | 'ws';
     /** Optional message pre-seeded as the first outbound message. */
     initialMessage?: string;
+    /**
+     * Local theme. Ranked BELOW whatever the merchant configured in the
+     * dashboard and ABOVE the SDK's built-in palette, merged per property, so a
+     * token you set here applies only where the dashboard did not set one.
+     */
+    theme?: ChatThemeOverride;
+}
+/**
+ * Local theme tokens. Every field is optional; colours are hex strings
+ * (`#RRGGBB` or `#AARRGGBB`). An unparseable value is ignored rather than
+ * throwing, so a bad colour can never crash the app.
+ */
+export interface ChatThemeOverride {
+    /**
+     * Force light or dark. Omit for "no opinion": the dashboard's mode wins if
+     * it set one, otherwise the device setting.
+     */
+    mode?: 'light' | 'dark';
+    chatBackground?: string;
+    headerBackground?: string;
+    headerPrimaryText?: string;
+    headerSecondaryText?: string;
+    headerIcon?: string;
+    closeButton?: string;
+    receivedBubble?: string;
+    receivedText?: string;
+    receivedTimestamp?: string;
+    sentBubble?: string;
+    sentText?: string;
+    sentTimestamp?: string;
+    systemMessageText?: string;
+    daySeparatorBackground?: string;
+    daySeparatorText?: string;
+    footerContainer?: string;
+    chatInputBackground?: string;
+    chatInputText?: string;
+    chatInputPlaceholder?: string;
+    chatInputBorder?: string;
+    sendButtonBackground?: string;
+    sendButtonIcon?: string;
+    attachmentButton?: string;
+    unreadBadgeBackground?: string;
+    unreadBadgeText?: string;
 }
 export interface ChatUser {
     customerName: string;
     customerEmail?: string;
+    /**
+     * Your reference for this customer. Sent for agent context but NOT trusted
+     * as identity: an id asserted by app code cannot be verified. For a trusted
+     * identity use `customerToken`.
+     */
     customerId?: string;
+    /**
+     * Chat identity token minted by YOUR backend with `createCsCustomerToken`
+     * and handed to the app. When set it is the authoritative identity: the
+     * server derives name, email and customer id from its signed claims, so a
+     * tampered app cannot impersonate another customer.
+     */
+    customerToken?: string;
 }
 export type AttachmentSourceType = 'auto' | 'base64' | 'dataUri' | 'file' | 'contentUri' | 'url';
 /**
@@ -101,9 +156,54 @@ export interface ChatMessage {
     totalMessages?: number;
 }
 export type NewinstanceChatErrorType = 'network' | 'validation' | 'auth' | 'system';
+/**
+ * Stable, cross-platform diagnostic codes. The same strings are emitted by the
+ * web, Android, iOS and Flutter SDKs, so `code` is the value to branch on and
+ * to quote in a support request.
+ */
+export type NewinstanceChatErrorCode = 
+/** The API key was rejected: wrong key, wrong environment, revoked, or expired. */
+'INVALID_PUBLIC_KEY'
+/** No API key was supplied. */
+ | 'MISSING_WIDGET_KEY'
+/** The key is valid but no chat configuration exists for the organization. */
+ | 'CHAT_CONFIG_UNAVAILABLE'
+/** The key and config are fine, but chat is switched off in the dashboard. */
+ | 'CHAT_DISABLED'
+/** Remote configuration could not be fetched; the built-in theme is in use. */
+ | 'CONFIG_FETCH_FAILED'
+/** The chat identity token was malformed, expired, or signed for another organization. */
+ | 'INVALID_IDENTITY_TOKEN'
+/** A request could not reach the backend at all. */
+ | 'NETWORK_ERROR'
+/** The realtime transport dropped and could not be re-established. */
+ | 'TRANSPORT_ERROR'
+/** Starting a conversation failed. */
+ | 'CHAT_INITIALIZATION_FAILED'
+/** A message could not be delivered. */
+ | 'MESSAGE_SEND_FAILED'
+/** An attachment could not be uploaded. */
+ | 'ATTACHMENT_FAILED'
+/** The backend answered, but not with anything the SDK could use. */
+ | 'SERVER_ERROR';
+/**
+ * Delivered on the `error` event. This is the channel for "why is my chat not
+ * working": it is never rendered inside the chat interface, and it never
+ * carries the API key, the identity token, or customer personal data.
+ */
 export interface NewinstanceChatError {
+    /** Stable code to branch on. Undefined only from SDK versions older than 0.3.0. */
+    code?: NewinstanceChatErrorCode;
+    /** Broad category, kept for backwards compatibility with 0.2.x handlers. */
     type: NewinstanceChatErrorType;
+    /** Safe to log and to show a developer. Not written for end users. */
     message: string;
+    /**
+     * Extra detail for developers, when the SDK had any that was safe to
+     * expose. Never a raw server response body.
+     */
+    developerMessage?: string;
+    /** False when the SDK has given up until the host fixes something. */
     recoverable: boolean;
 }
 /** Native event names. Subscribe with `sdk.addListener(event, handler)`. */

package/lib/typescript/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-newinstance-chat",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "New instance LiveAndAiChat React Native SDK \u2014 AI + live-agent chat, drop-in native chat screen for iOS and Android.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/index.tsx

@@ -15,13 +15,17 @@ import type {
 
 export type {
   AttachmentInput,
+  AttachmentUpdate,
+  ChatClosedEvent,
   ChatMessage,
+  ChatThemeOverride,
   ChatUser,
   ConnectionState,
   EventMap,
   EventName,
   NewinstanceChatConfig,
   NewinstanceChatError,
+  NewinstanceChatErrorCode,
   NewinstanceChatErrorType,
 } from './types';
 
@@ -54,11 +58,24 @@ export class NewinstanceChat {
    * Identify the customer. Safe to call before or after `initialize()`. If
    * called before `configure()` resolves, the user is queued and applied
    * once the native instance exists.
+   *
+   * Prefer `customerToken`: it is minted by your backend, so the server can
+   * verify who the customer is. `customerName` / `customerEmail` /
+   * `customerId` alone are client-asserted and are not trusted as identity.
    */
   setUser(user: ChatUser): void {
     NativeNewinstanceChat.setUser(user);
   }
 
+  /**
+   * Identify the customer with a backend-minted chat identity token only.
+   * Nothing else needs to be supplied: the server derives the name, email and
+   * customer id from the token's signed claims.
+   */
+  setUserToken(customerToken: string): void {
+    NativeNewinstanceChat.setUser({ customerName: 'Customer', customerToken });
+  }
+
   /**
    * Fetch org config, restore the saved conversation, and connect the
    * subscription transport in the background. Concurrent callers share

package/src/types.ts

@@ -15,12 +15,68 @@ export interface NewinstanceChatConfig {
   transport?: 'sse' | 'ws';
   /** Optional message pre-seeded as the first outbound message. */
   initialMessage?: string;
+  /**
+   * Local theme. Ranked BELOW whatever the merchant configured in the
+   * dashboard and ABOVE the SDK's built-in palette, merged per property, so a
+   * token you set here applies only where the dashboard did not set one.
+   */
+  theme?: ChatThemeOverride;
+}
+
+/**
+ * Local theme tokens. Every field is optional; colours are hex strings
+ * (`#RRGGBB` or `#AARRGGBB`). An unparseable value is ignored rather than
+ * throwing, so a bad colour can never crash the app.
+ */
+export interface ChatThemeOverride {
+  /**
+   * Force light or dark. Omit for "no opinion": the dashboard's mode wins if
+   * it set one, otherwise the device setting.
+   */
+  mode?: 'light' | 'dark';
+  chatBackground?: string;
+  headerBackground?: string;
+  headerPrimaryText?: string;
+  headerSecondaryText?: string;
+  headerIcon?: string;
+  closeButton?: string;
+  receivedBubble?: string;
+  receivedText?: string;
+  receivedTimestamp?: string;
+  sentBubble?: string;
+  sentText?: string;
+  sentTimestamp?: string;
+  systemMessageText?: string;
+  daySeparatorBackground?: string;
+  daySeparatorText?: string;
+  footerContainer?: string;
+  chatInputBackground?: string;
+  chatInputText?: string;
+  chatInputPlaceholder?: string;
+  chatInputBorder?: string;
+  sendButtonBackground?: string;
+  sendButtonIcon?: string;
+  attachmentButton?: string;
+  unreadBadgeBackground?: string;
+  unreadBadgeText?: string;
 }
 
 export interface ChatUser {
   customerName: string;
   customerEmail?: string;
+  /**
+   * Your reference for this customer. Sent for agent context but NOT trusted
+   * as identity: an id asserted by app code cannot be verified. For a trusted
+   * identity use `customerToken`.
+   */
   customerId?: string;
+  /**
+   * Chat identity token minted by YOUR backend with `createCsCustomerToken`
+   * and handed to the app. When set it is the authoritative identity: the
+   * server derives name, email and customer id from its signed claims, so a
+   * tampered app cannot impersonate another customer.
+   */
+  customerToken?: string;
 }
 
 export type AttachmentSourceType =
@@ -139,9 +195,55 @@ export type NewinstanceChatErrorType =
   | 'auth'
   | 'system';
 
+/**
+ * Stable, cross-platform diagnostic codes. The same strings are emitted by the
+ * web, Android, iOS and Flutter SDKs, so `code` is the value to branch on and
+ * to quote in a support request.
+ */
+export type NewinstanceChatErrorCode =
+  /** The API key was rejected: wrong key, wrong environment, revoked, or expired. */
+  | 'INVALID_PUBLIC_KEY'
+  /** No API key was supplied. */
+  | 'MISSING_WIDGET_KEY'
+  /** The key is valid but no chat configuration exists for the organization. */
+  | 'CHAT_CONFIG_UNAVAILABLE'
+  /** The key and config are fine, but chat is switched off in the dashboard. */
+  | 'CHAT_DISABLED'
+  /** Remote configuration could not be fetched; the built-in theme is in use. */
+  | 'CONFIG_FETCH_FAILED'
+  /** The chat identity token was malformed, expired, or signed for another organization. */
+  | 'INVALID_IDENTITY_TOKEN'
+  /** A request could not reach the backend at all. */
+  | 'NETWORK_ERROR'
+  /** The realtime transport dropped and could not be re-established. */
+  | 'TRANSPORT_ERROR'
+  /** Starting a conversation failed. */
+  | 'CHAT_INITIALIZATION_FAILED'
+  /** A message could not be delivered. */
+  | 'MESSAGE_SEND_FAILED'
+  /** An attachment could not be uploaded. */
+  | 'ATTACHMENT_FAILED'
+  /** The backend answered, but not with anything the SDK could use. */
+  | 'SERVER_ERROR';
+
+/**
+ * Delivered on the `error` event. This is the channel for "why is my chat not
+ * working": it is never rendered inside the chat interface, and it never
+ * carries the API key, the identity token, or customer personal data.
+ */
 export interface NewinstanceChatError {
+  /** Stable code to branch on. Undefined only from SDK versions older than 0.3.0. */
+  code?: NewinstanceChatErrorCode;
+  /** Broad category, kept for backwards compatibility with 0.2.x handlers. */
   type: NewinstanceChatErrorType;
+  /** Safe to log and to show a developer. Not written for end users. */
   message: string;
+  /**
+   * Extra detail for developers, when the SDK had any that was safe to
+   * expose. Never a raw server response body.
+   */
+  developerMessage?: string;
+  /** False when the SDK has given up until the host fixes something. */
   recoverable: boolean;
 }