react-native-newinstance-chat 0.1.2 → 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.1.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
@@ -86,17 +176,134 @@ unsub();
 ```
 
 Event names: `messageReceived`, `messageSent`, `agentTypingChanged`,
-`connectionStateChanged`, `unreadCountChanged`, `error`. See `src/types.ts`
-for payload shapes.
+`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
+screen went away: the in-chat close button, Android back navigation
+(button or gesture), an iOS dismissal gesture, `closeChat()`,
+`destroy()` (reason `session_ended`), or the host app navigating the
+screen away. Rerenders and lifecycle churn never produce duplicates.
+
+```ts
+useEffect(() => {
+  const unsub = sdk.addListener('chatClosed', (e) => {
+    // e.reason: 'close_button' | 'back_navigation' | 'gesture' |
+    //           'programmatic' | 'session_ended' | 'host_navigation'
+    // e.initiator: 'user' | 'host' | 'sdk'
+    // plus: timestamp, conversationId, assignmentId, channel,
+    //       previousState, unreadCount, hasDraft,
+    //       pendingAttachmentCount, metadata
+    analytics.track('chat_closed', { reason: e.reason });
+  });
+  return unsub; // always clean up on unmount
+}, []);
+```
+
+Ordering: `chatClosed` is emitted after the SDK has left the open
+state (`unreadCount` and `pendingAttachmentCount` reflect the moment of
+dismissal). The event never contains message contents, credentials, or
+attachment bytes.
 
 ### Sending messages programmatically
 
 ```ts
 sdk.sendMessage('Hi, I have a question.');
-sdk.attachFile({ uri: 'file:///…', name: 'screenshot.png', mimeType: 'image/png' });
 sdk.retryMessage(failedMessageId);
 ```
 
+### Programmatic attachments
+
+`attachFile` accepts base64, data URIs, local file paths,
+`content://` / `file://` URIs (picker outputs), and — when the native
+SDK is configured with `allowRemoteAttachmentUrls` — remote URLs.
+`sourceType: 'auto'` (the default) safely detects string inputs.
+
+```ts
+// Base64 (e.g. from a camera or canvas):
+const id = await sdk.attachFile({
+  source: pngBase64,
+  sourceType: 'base64',
+  name: 'photo.png',
+  mimeType: 'image/png',
+});
+
+// React Native document picker result:
+const [doc] = await pick(); // e.g. @react-native-documents/picker
+await sdk.attachFile({
+  source: doc.uri,          // content:// on Android, file:// on iOS
+  name: doc.name ?? 'document.pdf',
+  mimeType: doc.type ?? 'application/pdf',
+  size: doc.size ?? undefined,
+});
+
+// Data URI:
+await sdk.attachFile({ source: dataUri, name: 'chart.png' });
+```
+
+The returned promise resolves with the attachment **id** as soon as the
+request is accepted and queued. Validation and upload run in the
+background and never block the UI thread — failures surface as
+`attachmentUpdated` with `status: 'failed'` plus an `error` event — and
+the message is never sent until the upload succeeds (send drains only
+uploaded attachments). Track progress and results via
+`attachmentUpdated`:
+
+```ts
+sdk.addListener('attachmentUpdated', (a) => {
+  // a.status: 'queued' | 'uploading' | 'uploaded' | 'failed' | 'cancelled'
+  // a.progress: 0..1 real byte progress
+  if (a.status === 'failed') console.warn(a.error);
+});
+
+sdk.removeAttachment(id); // cancels an in-flight upload
+sdk.clearAttachments();
+```
+
+Validation happens before anything is queued: base64 must decode, URIs
+must be readable, files must be non-empty and at most 25 MB, the MIME
+type must be one of png/jpeg/webp/gif/pdf, a mismatched `size` is
+rejected as corruption, and the extension must agree with the MIME
+type. Attachment contents are never written to logs.
+
+Allowed MIME types and the 25 MB cap mirror the web widget; keys and
+limits are enforced again server-side.
+
 Handoff to a live agent and typing indicators are driven automatically
 by the native chat screen — there's nothing to wire up from the host.
 

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.1.1"
+  implementation "cloud.newinstance:liveandaichat:0.3.0"
 }

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

@@ -4,13 +4,21 @@ 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
 import cloud.newinstance.liveandaichat.model.ChatMessage
 import cloud.newinstance.liveandaichat.model.TransportMode
+import cloud.newinstance.liveandaichat.upload.QueuedAttachment
 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
 
@@ -35,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?) {
@@ -62,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)
@@ -83,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)
@@ -124,24 +159,57 @@ class NewinstanceChatModule(reactContext: ReactApplicationContext) :
       promise.reject("E_NOT_CONFIGURED", "configure() must be called first")
       return
     }
-    val uri = opts.getString("uri")
     val name = opts.getString("name")
-    val mimeType = opts.getString("mimeType")
-    if (uri == null || name == null || mimeType == null) {
-      promise.reject("E_ARGS", "uri, name, mimeType are required")
+    if (name.isNullOrBlank()) {
+      promise.reject("E_ARGS", "name is required")
+      return
+    }
+    val sourceValue = opts.getString("source") ?: opts.getString("uri")
+    if (sourceValue.isNullOrBlank()) {
+      promise.reject("E_ARGS", "source (or legacy uri) is required")
       return
     }
+    val sourceType = opts.getString("sourceType") ?: "auto"
+    val source = AttachmentSource.fromTypeName(sourceType, sourceValue)
+    if (source == null) {
+      promise.reject(
+        "E_SOURCE",
+        if (sourceType == "auto") "Could not detect the attachment source type — pass sourceType explicitly"
+        else "Unknown sourceType: $sourceType",
+      )
+      return
+    }
+    val mimeType = opts.getString("mimeType")
+    val declaredSize = if (opts.hasKey("size") && !opts.isNull("size")) opts.getDouble("size").toLong() else null
+    val metadata = mutableMapOf<String, String>()
+    if (opts.hasKey("metadata") && !opts.isNull("metadata")) {
+      val map = opts.getMap("metadata")
+      map?.entryIterator?.forEach { (key, value) -> metadata[key] = value.toString() }
+    }
     try {
-      val bytes = reactApplicationContext.contentResolver
-        .openInputStream(android.net.Uri.parse(uri))?.use { it.readBytes() }
-        ?: throw java.io.IOException("Could not open content URI: $uri")
-      current.attachFile(bytes, name, mimeType, uri)
-      promise.resolve(null)
+      val id = current.attach(
+        AttachmentRequest(
+          source = source,
+          name = name,
+          mimeType = mimeType,
+          declaredSize = declaredSize,
+          metadata = metadata,
+        ),
+      )
+      promise.resolve(id)
     } catch (e: Exception) {
-      promise.reject("E_READ", e.message, e)
+      promise.reject("E_ATTACH", e.message, e)
     }
   }
 
+  override fun removeAttachment(id: String) {
+    sdk?.removeAttachment(id)
+  }
+
+  override fun clearAttachments() {
+    sdk?.clearAttachments()
+  }
+
   override fun destroy() {
     sdk?.destroy()
     sdk = null
@@ -170,14 +238,79 @@ class NewinstanceChatModule(reactContext: ReactApplicationContext) :
   override fun onUnreadCountChange(count: Int) {
     emit("unreadCountChanged", count)
   }
+  override fun onAttachmentUpdate(attachment: QueuedAttachment) {
+    val map = Arguments.createMap()
+    map.putString("id", attachment.id)
+    map.putString("name", attachment.name)
+    map.putString("mimeType", attachment.mimeType)
+    map.putDouble("size", attachment.size.toDouble())
+    map.putString("status", attachment.status.name.lowercase())
+    map.putDouble("progress", attachment.progress.toDouble())
+    attachment.publicUrl?.let { map.putString("url", it) }
+    attachment.errorReason?.let { map.putString("error", it) }
+    emit("attachmentUpdated", map)
+  }
+
+  override fun onChatClosed(event: ChatCloseEvent) {
+    val map = Arguments.createMap()
+    map.putString("reason", event.reason.wire)
+    map.putString("initiator", event.initiator.wire)
+    map.putDouble("timestamp", event.timestamp.toDouble())
+    event.conversationId?.let { map.putString("conversationId", it) }
+    event.assignmentId?.let { map.putString("assignmentId", it) }
+    map.putString("channel", event.channel)
+    map.putString("previousState", event.previousState)
+    map.putInt("unreadCount", event.unreadCount)
+    map.putBoolean("hasDraft", event.hasDraft)
+    map.putInt("pendingAttachmentCount", event.pendingAttachmentCount)
+    val meta = Arguments.createMap()
+    event.metadata.forEach { (k, v) -> meta.putString(k, v) }
+    map.putMap("metadata", meta)
+    emit("chatClosed", map)
+  }
+
   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/NewinstanceChat.mm

@@ -76,6 +76,16 @@ RCT_EXPORT_MODULE()
   [_impl attachFile:opts resolver:resolve rejecter:reject];
 }
 
+- (void)removeAttachment:(NSString *)attachmentId
+{
+  [_impl removeAttachment:attachmentId];
+}
+
+- (void)clearAttachments
+{
+  [_impl clearAttachments];
+}
+
 // NativeEventEmitter wires these so it can track subscriber counts. The
 // actual event payloads flow through RCTDeviceEventEmitter, so these are
 // intentional no-ops.

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 {
@@ -140,26 +163,53 @@ public final class NewinstanceChatImpl: NSObject, LiveAndAiChatDelegate {
       rejecter("E_NOT_CONFIGURED", "configure() must be called first", nil)
       return
     }
-    guard let uri = opts["uri"] as? String,
-          let name = opts["name"] as? String,
-          let mimeType = opts["mimeType"] as? String,
-          let url = URL(string: uri) else {
-      rejecter("E_ARGS", "uri, name, mimeType are required", nil)
+    guard let name = opts["name"] as? String, !name.isEmpty else {
+      rejecter("E_ARGS", "name is required", nil)
       return
     }
-    DispatchQueue.global(qos: .userInitiated).async {
-      do {
-        let data = try Data(contentsOf: url)
-        DispatchQueue.main.async {
-          sdk.attachFile(data: data, name: name, mimeType: mimeType, previewUri: uri)
-          resolver(nil)
-        }
-      } catch {
-        rejecter("E_READ", "Failed to read file: \(error.localizedDescription)", error)
-      }
+    guard let sourceValue = (opts["source"] as? String) ?? (opts["uri"] as? String), !sourceValue.isEmpty else {
+      rejecter("E_ARGS", "source (or legacy uri) is required", nil)
+      return
+    }
+    let sourceType = (opts["sourceType"] as? String) ?? "auto"
+    guard let source = AttachmentSource.fromTypeName(sourceType, value: sourceValue) else {
+      rejecter(
+        "E_SOURCE",
+        sourceType == "auto"
+          ? "Could not detect the attachment source type — pass sourceType explicitly"
+          : "Unknown sourceType: \(sourceType)",
+        nil
+      )
+      return
+    }
+    let mimeType = opts["mimeType"] as? String
+    let declaredSize = (opts["size"] as? NSNumber)?.int64Value
+    var metadata: [String: String] = [:]
+    if let raw = opts["metadata"] as? [String: Any] {
+      for (key, value) in raw { metadata[key] = String(describing: value) }
+    }
+    let request = AttachmentRequest(
+      source: source,
+      name: name,
+      mimeType: mimeType,
+      declaredSize: declaredSize,
+      metadata: metadata
+    )
+    DispatchQueue.main.async {
+      let id = sdk.attach(request)
+      resolver(id)
     }
   }
 
+  @objc(removeAttachment:)
+  public func removeAttachment(_ id: String) {
+    DispatchQueue.main.async { [weak self] in self?.sdk?.removeAttachment(id: id) }
+  }
+
+  @objc public func clearAttachments() {
+    DispatchQueue.main.async { [weak self] in self?.sdk?.clearAttachments() }
+  }
+
   @objc public func destroy() {
     DispatchQueue.main.async { [weak self] in
       guard let self = self else { return }
@@ -171,6 +221,41 @@ public final class NewinstanceChatImpl: NSObject, LiveAndAiChatDelegate {
 
   // MARK: - LiveAndAiChatDelegate
 
+  public func unreadCountDidChange(_ count: Int) {
+    emitter?.emitEvent("unreadCountChanged", body: count)
+  }
+
+  public func attachmentDidUpdate(_ attachment: QueuedAttachment) {
+    var body: [String: Any] = [
+      "id": attachment.id,
+      "name": attachment.name,
+      "mimeType": attachment.mimeType,
+      "size": attachment.size,
+      "status": attachment.status.rawValue,
+      "progress": attachment.progress,
+    ]
+    if let url = attachment.publicUrl { body["url"] = url }
+    if let error = attachment.errorReason { body["error"] = error }
+    emitter?.emitEvent("attachmentUpdated", body: body)
+  }
+
+  public func chatDidClose(_ event: ChatCloseEvent) {
+    var body: [String: Any] = [
+      "reason": event.reason.rawValue,
+      "initiator": event.initiator.rawValue,
+      "timestamp": event.timestamp,
+      "channel": event.channel,
+      "previousState": event.previousState,
+      "unreadCount": event.unreadCount,
+      "hasDraft": event.hasDraft,
+      "pendingAttachmentCount": event.pendingAttachmentCount,
+      "metadata": event.metadata,
+    ]
+    if let id = event.conversationId { body["conversationId"] = id }
+    if let id = event.assignmentId { body["assignmentId"] = id }
+    emitter?.emitEvent("chatClosed", body: body)
+  }
+
   public func didReceiveMessage(_ message: ChatMessage) {
     emitter?.emitEvent("messageReceived", body: Self.chatMessageToDict(message))
   }
@@ -185,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,