@kindly-ai/react-native 0.1.0

package/src/NativeKindlyReactNative.ts

@@ -0,0 +1,80 @@
+// TurboModule spec for the @kindly-ai/react-native package.
+//
+// Codegen INPUT — `react-native` reads this at build time and generates the
+// abstract Spec class on iOS (Obj-C++ header) and Android (Kotlin abstract
+// class). The native module classes extend those.
+//
+// Convention used here: every method takes flat primitive parameters and
+// returns either a primitive or a Promise. We deliberately avoid nested
+// struct args (`(args: { ... })`) because codegen generates JS::Native*Args
+// C++ structs for those, which add fragility without buying anything for
+// our use case. This matches the scaffolded `multiply()` example pattern.
+//
+// Filename MUST match `Native<ModuleName>.ts`. ModuleName here is
+// `KindlyReactNative` — this becomes the native module name returned by
+// `getName()` and the registry key. Customer-facing imports come from the
+// package, not the module name.
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  // Lifecycle
+  start(botKey: string, languageCode: string | null, hasAuthCallback: boolean): void;
+  displayChat(languageCode: string | null, triggerDialogueId: string | null): void;
+  launchChat(triggerDialogueId: string | null): void;
+  closeChat(): void;
+  endChat(): Promise<void>;
+  kill(): Promise<void>;
+  setLanguage(languageCode: string): Promise<void>;
+
+  // Messaging — newContext map shape: { [key: string]: string }
+  sendMessage(
+    message: string,
+    newContext: { [key: string]: string } | null
+  ): Promise<{ [key: string]: unknown } | null>;
+  setNewContext(context: { [key: string]: string }): void;
+  clearNewContext(): void;
+  triggerDialogue(dialogueId: string): void;
+  clearTriggerDialogue(): void;
+  handleUrl(url: string): Promise<boolean>;
+
+  // Theme — colors map shape: { [key: string]: number | null }
+  setCustomTheme(colors: { [key: string]: number | null }): void;
+  clearCustomTheme(): void;
+
+  // Push
+  setAPNSDeviceToken(token: string): void;
+  saveNotificationToken(token: string): void;
+  handleNotification(data: { [key: string]: unknown }): void;
+  isKindlyNotification(data: { [key: string]: unknown }): boolean;
+
+  // State / settings
+  saveAuthToken(token: string): Promise<boolean>;
+  isChatDisplayed(): Promise<boolean>;
+  setVerboseLogging(enabled: boolean): void;
+  setCrashReporting(enabled: boolean): void;
+
+  // Round-trips for sync-style native→JS→native callbacks.
+  // Native fires events ('KindlyGetAuthToken', 'KindlyShouldHandle*') with
+  // a requestId; JS replies via these methods. Native blocks on a
+  // Map<requestId, Deferred> with a 5-second timeout, falling back to a
+  // safe default if JS is silent.
+  respondToAuthToken(requestId: string, token: string | null): void;
+  respondToShouldHandle(requestId: string, value: boolean): void;
+
+  // Delegate gating — flips on/off the bridge-level routing for each callback.
+  setDelegate(
+    onButtonPressed: boolean,
+    shouldHandleLink: boolean,
+    shouldHandleNotification: boolean,
+    onHandover: boolean
+  ): void;
+  callHandover(): void;
+
+  // RN bridge bookkeeping — required when the module emits events (iOS only
+  // looks at this; on Android RCTDeviceEventEmitter manages itself).
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('KindlyReactNative');

package/src/index.tsx

@@ -0,0 +1,353 @@
+// Kindly Chat SDK — public React Native surface.
+//
+// Thin TS facade over the native TurboModule (`KindlyReactNative`). Mirrors
+// the Flutter SDK's public API 1:1. Each method delegates to one or more
+// methods on the spec, plus a tiny amount of bookkeeping in JS for the
+// auth-token + delegate round-trips (the native side has no way to call
+// JS synchronously, so we pair `*Request` events with a `respondTo*` method).
+//
+// Customers do `import { KindlySDK } from '@kindly-ai/react-native'`. The
+// internal native-module name `KindlyReactNative` is intentionally not
+// exported — it's an implementation detail.
+import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
+import NativeKindly from './NativeKindlyReactNative';
+
+/** Callback invoked by the SDK when it needs a fresh JWT auth token. */
+export type AuthTokenCallback = () => Promise<string | null>;
+
+/** Callback invoked when a handover to a human agent is initiated. */
+export type HandoverCallback = () => void;
+
+/**
+ * Fired by the SDK when the user taps a chat button.
+ *
+ * `button` keys: `id`, `type`, `label`, `value`, `index`, `hasBeenSelected`.
+ * `chatLog` is the full conversation up to this point.
+ */
+export type KindlyButtonPressedCallback = (
+  button: { [key: string]: unknown },
+  chatLog: Array<{ [key: string]: unknown }>
+) => void;
+
+/**
+ * Asked by the SDK before opening a link the user tapped inside chat.
+ *
+ * Return `true` to let the SDK open it (default), or `false` to take over.
+ */
+export type KindlyLinkInterceptCallback = (url: string) => boolean;
+
+/**
+ * Asked by the SDK before presenting an incoming Kindly silent push.
+ *
+ * Return `true` to let the SDK present it (default), or `false` to take over.
+ */
+export type KindlyNotificationInterceptCallback = (notification: {
+  [key: string]: unknown;
+}) => boolean;
+
+/** Typed bag of theme colors (ARGB ints — use the helpers below). */
+export interface KindlyTheme {
+  background?: number;
+  botMessageBackground?: number;
+  botMessageText?: number;
+  buttonBackground?: number;
+  buttonOutline?: number;
+  buttonSelectedBackground?: number;
+  buttonText?: number;
+  defaultShadow?: number;
+  inputBackground?: number;
+  inputCursor?: number;
+  inputText?: number;
+  navBarBackground?: number;
+  navBarText?: number;
+  userMessageBackground?: number;
+  userMessageText?: number;
+  chatLogElements?: number;
+  maintenanceHeaderBackground?: number;
+}
+
+/**
+ * Convert a `#RRGGBB` or `#AARRGGBB` hex string to the ARGB int form the
+ * SDK expects. Equivalent to Flutter's `Color.value`.
+ */
+export function hexColor(hex: string): number {
+  const cleaned = hex.replace(/^#/, '');
+  const v = parseInt(cleaned, 16);
+  if (cleaned.length === 6) {
+    return (0xff000000 | v) >>> 0;
+  }
+  if (cleaned.length === 8) {
+    return v >>> 0;
+  }
+  throw new Error(`hexColor: expected #RRGGBB or #AARRGGBB, got "${hex}"`);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Native-event wiring for native→JS callbacks.
+//
+// Native fires events via RCTDeviceEventEmitter; JS attaches once on first use
+// and dispatches to the registered callbacks. Sync-bool answers
+// (`shouldHandleLink` / `shouldHandleNotification`) are returned via a
+// `respondToShouldHandle` round-trip — native blocks on a Map<requestId,
+// Deferred> with a 5s timeout, falling back to `true` if JS is slow or
+// silent. Same semantics as the Flutter SDK's blocking-bool pattern.
+// ────────────────────────────────────────────────────────────────────────────
+const eventEmitter = new NativeEventEmitter(
+  Platform.OS === 'ios'
+    ? (NativeModules.KindlyReactNative as unknown as undefined)
+    : undefined
+);
+
+let authTokenCallback: AuthTokenCallback | null = null;
+let handoverCallback: HandoverCallback | null = null;
+let onButtonPressed: KindlyButtonPressedCallback | null = null;
+let shouldHandleLink: KindlyLinkInterceptCallback | null = null;
+let shouldHandleNotification: KindlyNotificationInterceptCallback | null = null;
+
+let listenersAttached = false;
+
+function attachListeners(): void {
+  if (listenersAttached) return;
+  listenersAttached = true;
+
+  // RN's NativeEventEmitter.addListener types its callback as
+  // `(...args: readonly Object[]) => unknown` — we widen each event-shape
+  // type inside the handler instead of trying to fight the parameter type.
+  eventEmitter.addListener('KindlyGetAuthToken', async (raw: unknown) => {
+    const event = raw as { requestId: string };
+    if (authTokenCallback == null) {
+      NativeKindly.respondToAuthToken(event.requestId, null);
+      return;
+    }
+    try {
+      const token = await authTokenCallback();
+      NativeKindly.respondToAuthToken(event.requestId, token);
+    } catch {
+      NativeKindly.respondToAuthToken(event.requestId, null);
+    }
+  });
+
+  eventEmitter.addListener('KindlyOnHandover', () => {
+    handoverCallback?.();
+  });
+
+  eventEmitter.addListener('KindlyOnButtonPressed', (raw: unknown) => {
+    const event = raw as {
+      button: { [key: string]: unknown };
+      chatLog: Array<{ [key: string]: unknown }>;
+    };
+    onButtonPressed?.(event.button, event.chatLog);
+  });
+
+  eventEmitter.addListener('KindlyShouldHandleLink', (raw: unknown) => {
+    const event = raw as { requestId: string; url: string };
+    const value = shouldHandleLink ? shouldHandleLink(event.url) : true;
+    NativeKindly.respondToShouldHandle(event.requestId, value);
+  });
+
+  eventEmitter.addListener(
+    'KindlyShouldHandleNotification',
+    (raw: unknown) => {
+      const event = raw as {
+        requestId: string;
+        notification: { [key: string]: unknown };
+      };
+      const value = shouldHandleNotification
+        ? shouldHandleNotification(event.notification)
+        : true;
+      NativeKindly.respondToShouldHandle(event.requestId, value);
+    }
+  );
+}
+
+/**
+ * Main Kindly SDK entry point.
+ *
+ * Thin facade over the public `EntryPoint` API of the native iOS
+ * (`KindlyChatClient`) and Android (`ChatKindlySDK`) SDKs.
+ */
+export class KindlySDK {
+  /** Initialize the SDK. Must be called before any other method. */
+  static start(args: {
+    botKey: string;
+    languageCode?: string;
+    authTokenCallback?: AuthTokenCallback;
+  }): void {
+    attachListeners();
+    authTokenCallback = args.authTokenCallback ?? null;
+    NativeKindly.start(
+      args.botKey,
+      args.languageCode ?? null,
+      args.authTokenCallback != null
+    );
+  }
+
+  /** Show the chat UI. */
+  static displayChat(
+    args: { languageCode?: string; triggerDialogueId?: string } = {}
+  ): void {
+    NativeKindly.displayChat(
+      args.languageCode ?? null,
+      args.triggerDialogueId ?? null
+    );
+  }
+
+  /** Connect (if needed) and show chat. Recommended on Android. */
+  static launchChat(args: { triggerDialogueId?: string } = {}): void {
+    NativeKindly.launchChat(args.triggerDialogueId ?? null);
+  }
+
+  /** Dismiss the chat UI without ending the session. */
+  static closeChat(): void {
+    NativeKindly.closeChat();
+  }
+
+  /** End the chat session: clears messages, token, dismisses UI. */
+  static endChat(): Promise<void> {
+    return NativeKindly.endChat();
+  }
+
+  /** Tear the SDK down completely; call start() again before reuse. */
+  static kill(): Promise<void> {
+    return NativeKindly.kill();
+  }
+
+  /** Update the language for the current session. */
+  static setLanguage(languageCode: string): Promise<void> {
+    return NativeKindly.setLanguage(languageCode);
+  }
+
+  /**
+   * Send a message programmatically. Returns the reconciled message map
+   * (id, text, created, sender, …) or rejects on failure.
+   */
+  static sendMessage(
+    text: string,
+    options?: { newContext?: { [key: string]: string } }
+  ): Promise<{ [key: string]: unknown } | null> {
+    return NativeKindly.sendMessage(text, options?.newContext ?? null);
+  }
+
+  /** Apply a custom theme. Pass undefined fields to keep the default. */
+  static setCustomTheme(theme: KindlyTheme): void {
+    const colors: { [key: string]: number | null } = {};
+    (Object.keys(theme) as Array<keyof KindlyTheme>).forEach((k) => {
+      colors[k] = theme[k] ?? null;
+    });
+    NativeKindly.setCustomTheme(colors);
+  }
+
+  /** Clear custom theme; revert to default / API-supplied theme. */
+  static clearCustomTheme(): void {
+    NativeKindly.clearCustomTheme();
+  }
+
+  /** Stage context attached to the next message or button click. */
+  static setNewContext(context: { [key: string]: string }): void {
+    NativeKindly.setNewContext(context);
+  }
+
+  /** Clear any context staged via setNewContext. */
+  static clearNewContext(): void {
+    NativeKindly.clearNewContext();
+  }
+
+  /** Save a JWT auth token (iOS keychain). On Android always returns true. */
+  static saveAuthToken(token: string): Promise<boolean> {
+    return NativeKindly.saveAuthToken(token);
+  }
+
+  /** Register the APNS device token. iOS only — no-op on Android. */
+  static setAPNSDeviceToken(token: string): void {
+    if (Platform.OS === 'ios') {
+      NativeKindly.setAPNSDeviceToken(token);
+    }
+  }
+
+  /** Register the FCM token. Android only — no-op on iOS. */
+  static saveNotificationToken(token: string): void {
+    if (Platform.OS === 'android') {
+      NativeKindly.saveNotificationToken(token);
+    }
+  }
+
+  /** Forward an incoming push notification to the SDK. */
+  static handleNotification(data: { [key: string]: unknown }): void {
+    NativeKindly.handleNotification(data);
+  }
+
+  /** Returns true if the given push payload originated from Kindly. */
+  static isKindlyNotification(data: { [key: string]: unknown }): boolean {
+    return NativeKindly.isKindlyNotification(data);
+  }
+
+  /** Trigger a specific dialogue by id. The SDK must be connected. */
+  static triggerDialogue(dialogueId: string): void {
+    NativeKindly.triggerDialogue(dialogueId);
+  }
+
+  /** Clear any pending trigger-dialogue request (Android only). */
+  static clearTriggerDialogue(): void {
+    NativeKindly.clearTriggerDialogue();
+  }
+
+  /** Handle a Kindly deep-link URL (e.g. `kindly://chat/dialogue/{id}`). */
+  static handleUrl(url: string): Promise<boolean> {
+    return NativeKindly.handleUrl(url);
+  }
+
+  /** Initiate a handover to a human agent. */
+  static callHandover(callback: HandoverCallback): void {
+    attachListeners();
+    handoverCallback = callback;
+    NativeKindly.callHandover();
+  }
+
+  /** Whether the chat UI is currently displayed (iOS only — Android always false). */
+  static isChatDisplayed(): Promise<boolean> {
+    return NativeKindly.isChatDisplayed();
+  }
+
+  /** Toggle verbose SDK logging. */
+  static setVerboseLogging(enabled: boolean): void {
+    NativeKindly.setVerboseLogging(enabled);
+  }
+
+  /** Toggle Sentry crash reporting from inside the SDK. */
+  static setCrashReporting(enabled: boolean): void {
+    NativeKindly.setCrashReporting(enabled);
+  }
+
+  /**
+   * Register host-app callbacks for chat-button presses, link interception,
+   * and notification interception. Mirrors the native delegate protocols.
+   *
+   * `shouldHandleLink` / `shouldHandleNotification` have a 5-second native
+   * timeout — return quickly. After timeout the SDK falls back to its
+   * default `true` so the UI doesn't hang on a slow JS callback.
+   */
+  static setDelegate(args: {
+    onButtonPressed?: KindlyButtonPressedCallback;
+    shouldHandleLink?: KindlyLinkInterceptCallback;
+    shouldHandleNotification?: KindlyNotificationInterceptCallback;
+  }): void {
+    attachListeners();
+    onButtonPressed = args.onButtonPressed ?? null;
+    shouldHandleLink = args.shouldHandleLink ?? null;
+    shouldHandleNotification = args.shouldHandleNotification ?? null;
+    NativeKindly.setDelegate(
+      onButtonPressed != null,
+      shouldHandleLink != null,
+      shouldHandleNotification != null,
+      handoverCallback != null
+    );
+  }
+
+  /** Clear all delegate callbacks set via setDelegate. */
+  static clearDelegate(): void {
+    onButtonPressed = null;
+    shouldHandleLink = null;
+    shouldHandleNotification = null;
+    NativeKindly.setDelegate(false, false, false, handoverCallback != null);
+  }
+}