@rematter/pylon-react-native 0.1.4

package/lib/PylonChatWidget.ios.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+import type { PylonChatViewRef } from "./PylonChatView";
+import type { PylonChatWidgetProps } from "./PylonChatWidget";
+/**
+ * iOS implementation - simple passthrough.
+ *
+ * iOS uses native hitTest for touch pass-through, so no proxy logic needed.
+ *
+ * State Management:
+ * - State lives entirely in native layer (no React state needed for iOS)
+ * - Imperative methods call native, which handles everything
+ * - Events are simply forwarded to user's listener
+ */
+export declare const PylonChatWidget: React.ForwardRefExoticComponent<PylonChatWidgetProps & React.RefAttributes<PylonChatViewRef>>;

package/lib/PylonChatWidget.ios.js

@@ -0,0 +1,79 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PylonChatWidget = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const PylonChatView_1 = require("./PylonChatView");
+/**
+ * iOS implementation - simple passthrough.
+ *
+ * iOS uses native hitTest for touch pass-through, so no proxy logic needed.
+ *
+ * State Management:
+ * - State lives entirely in native layer (no React state needed for iOS)
+ * - Imperative methods call native, which handles everything
+ * - Events are simply forwarded to user's listener
+ */
+exports.PylonChatWidget = (0, react_1.forwardRef)(({ config, user, listener, style, topInset }, ref) => {
+    // Internal ref - typed as any since iOS doesn't need clickElementAtSelector.
+    const chatRef = (0, react_1.useRef)(null);
+    // Forward ref methods - all state managed in native layer
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        openChat: () => chatRef.current?.openChat(),
+        closeChat: () => chatRef.current?.closeChat(),
+        showChatBubble: () => chatRef.current?.showChatBubble(),
+        hideChatBubble: () => chatRef.current?.hideChatBubble(),
+        showNewMessage: (message, isHtml) => chatRef.current?.showNewMessage(message, isHtml),
+        setNewIssueCustomFields: (fields) => chatRef.current?.setNewIssueCustomFields(fields),
+        setTicketFormFields: (fields) => chatRef.current?.setTicketFormFields(fields),
+        updateEmailHash: (emailHash) => chatRef.current?.updateEmailHash(emailHash),
+        showTicketForm: (slug) => chatRef.current?.showTicketForm(slug),
+        showKnowledgeBaseArticle: (articleId) => chatRef.current?.showKnowledgeBaseArticle(articleId),
+    }));
+    // Event handlers - forward to user's listener
+    const handleChatOpened = (0, react_1.useCallback)(() => {
+        listener?.onChatOpened?.();
+    }, [listener]);
+    const handleChatClosed = (0, react_1.useCallback)((wasOpen) => {
+        listener?.onChatClosed?.(wasOpen);
+    }, [listener]);
+    return (<PylonChatView_1.PylonChatView ref={chatRef} style={style || react_native_1.StyleSheet.absoluteFillObject} config={config} user={user} topInset={topInset} listener={{
+            ...listener,
+            onChatOpened: handleChatOpened,
+            onChatClosed: handleChatClosed,
+        }}/>);
+});
+exports.PylonChatWidget.displayName = "PylonChatWidget";

package/lib/PylonModule.d.ts

@@ -0,0 +1,32 @@
+import type { PylonConfig, PylonUser } from "./types";
+/**
+ * Pylon SDK - Singleton for managing global configuration.
+ *
+ * Note: This is optional - you can also pass config directly to PylonChatView.
+ * This singleton is useful if you want to initialize once and reuse across multiple views.
+ */
+export declare class Pylon {
+    private static instance;
+    private _config?;
+    private _user?;
+    private constructor();
+    static get shared(): Pylon;
+    /**
+     * Initialize the Pylon SDK with configuration.
+     */
+    initialize(config: PylonConfig): void;
+    /**
+     * Set the current user for the chat.
+     */
+    setUser(user: PylonUser): void;
+    /**
+     * Get the current configuration.
+     */
+    get config(): PylonConfig | undefined;
+    /**
+     * Get the current user.
+     */
+    get user(): PylonUser | undefined;
+}
+declare const _default: Pylon;
+export default _default;

package/lib/PylonModule.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pylon = void 0;
+/**
+ * Pylon SDK - Singleton for managing global configuration.
+ *
+ * Note: This is optional - you can also pass config directly to PylonChatView.
+ * This singleton is useful if you want to initialize once and reuse across multiple views.
+ */
+class Pylon {
+    constructor() { }
+    static get shared() {
+        if (!Pylon.instance) {
+            Pylon.instance = new Pylon();
+        }
+        return Pylon.instance;
+    }
+    /**
+     * Initialize the Pylon SDK with configuration.
+     */
+    initialize(config) {
+        this._config = config;
+    }
+    /**
+     * Set the current user for the chat.
+     */
+    setUser(user) {
+        this._user = user;
+    }
+    /**
+     * Get the current configuration.
+     */
+    get config() {
+        return this._config;
+    }
+    /**
+     * Get the current user.
+     */
+    get user() {
+        return this._user;
+    }
+}
+exports.Pylon = Pylon;
+exports.default = Pylon.shared;

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { PylonChatView } from "./PylonChatView";
+export type { PylonChatViewRef, PylonChatViewInternalRef, } from "./PylonChatView";
+export { PylonChatWidget } from "./PylonChatWidget";
+export { Pylon, default as PylonSDK } from "./PylonModule";
+export type { InteractiveBound, PylonChatListener, PylonConfig, PylonUser, } from "./types";

package/lib/index.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PylonSDK = exports.Pylon = exports.PylonChatWidget = exports.PylonChatView = void 0;
+var PylonChatView_1 = require("./PylonChatView");
+Object.defineProperty(exports, "PylonChatView", { enumerable: true, get: function () { return PylonChatView_1.PylonChatView; } });
+// React Native will automatically resolve to .ios.tsx or .android.tsx at runtime
+// TypeScript just needs to find the types from one of them
+var PylonChatWidget_1 = require("./PylonChatWidget");
+Object.defineProperty(exports, "PylonChatWidget", { enumerable: true, get: function () { return PylonChatWidget_1.PylonChatWidget; } });
+var PylonModule_1 = require("./PylonModule");
+Object.defineProperty(exports, "Pylon", { enumerable: true, get: function () { return PylonModule_1.Pylon; } });
+Object.defineProperty(exports, "PylonSDK", { enumerable: true, get: function () { return __importDefault(PylonModule_1).default; } });

package/lib/types.d.ts

@@ -0,0 +1,34 @@
+export interface PylonConfig {
+    appId: string;
+    enableLogging?: boolean;
+    primaryColor?: string;
+    debugMode?: boolean;
+    widgetBaseUrl?: string;
+    widgetScriptUrl?: string;
+}
+export interface PylonUser {
+    email: string;
+    name: string;
+    avatarUrl?: string;
+    emailHash?: string;
+    accountId?: string;
+    accountExternalId?: string;
+}
+export interface InteractiveBound {
+    selector: string;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface PylonChatListener {
+    onPylonLoaded?: () => void;
+    onPylonInitialized?: () => void;
+    onPylonReady?: () => void;
+    onMessageReceived?: (message: string) => void;
+    onChatOpened?: () => void;
+    onChatClosed?: (wasOpen: boolean) => void;
+    onPylonError?: (error: string) => void;
+    onUnreadCountChanged?: (count: number) => void;
+    onInteractiveBoundsChanged?: (bounds: InteractiveBound) => void;
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rematter/pylon-react-native",
+  "version": "0.1.4",
+  "description": "Pylon Chat SDK for React Native",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "homepage": "https://github.com/usepylon/pylon-chat-sdk",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "copy-sdks": "bash scripts/copy-native-sdks.sh",
+    "prepare": "npm run copy-sdks && npm run build"
+  },
+  "keywords": [
+    "pylon",
+    "chat",
+    "react-native",
+    "customer-support",
+    "native-module"
+  ],
+  "author": "Pylon",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "lib",
+    "src",
+    "ios",
+    "android",
+    "RNPylonChat.podspec"
+  ]
+}

package/src/PylonChatView.tsx

@@ -0,0 +1,170 @@
+import React, { useImperativeHandle, useRef } from "react";
+import {
+  findNodeHandle,
+  requireNativeComponent,
+  UIManager,
+  ViewStyle,
+} from "react-native";
+import type { PylonChatListener, PylonConfig, PylonUser } from "./types";
+
+// Public API exposed to SDK users.
+export interface PylonChatViewRef {
+  openChat: () => void;
+  closeChat: () => void;
+  showChatBubble: () => void;
+  hideChatBubble: () => void;
+  showNewMessage: (message: string, isHtml?: boolean) => void;
+  setNewIssueCustomFields: (fields: Record<string, any>) => void;
+  setTicketFormFields: (fields: Record<string, any>) => void;
+  updateEmailHash: (emailHash: string | null) => void;
+  showTicketForm: (slug: string) => void;
+  showKnowledgeBaseArticle: (articleId: string) => void;
+}
+
+// Internal interface with additional methods for platform-specific implementations.
+export interface PylonChatViewInternalRef extends PylonChatViewRef {
+  clickElementAtSelector: (selector: string) => void;
+}
+
+interface PylonChatViewProps {
+  config: PylonConfig;
+  user?: PylonUser;
+  style?: ViewStyle;
+  listener?: PylonChatListener;
+  topInset?: number;
+}
+
+interface NativePylonChatViewProps {
+  style?: ViewStyle;
+  pointerEvents?: "box-none" | "none" | "box-only" | "auto";
+  appId: string;
+  widgetBaseUrl?: string;
+  widgetScriptUrl?: string;
+  enableLogging?: boolean;
+  debugMode?: boolean;
+  primaryColor?: string;
+  userEmail?: string;
+  userName?: string;
+  userAvatarUrl?: string;
+  userEmailHash?: string;
+  userAccountId?: string;
+  userAccountExternalId?: string;
+  topInset?: number;
+  onPylonLoaded?: () => void;
+  onPylonInitialized?: () => void;
+  onPylonReady?: () => void;
+  onChatOpened?: () => void;
+  onChatClosed?: (event: { nativeEvent: { wasOpen: boolean } }) => void;
+  onUnreadCountChanged?: (event: { nativeEvent: { count: number } }) => void;
+  onMessageReceived?: (event: { nativeEvent: { message: string } }) => void;
+  onPylonError?: (event: { nativeEvent: { error: string } }) => void;
+  onInteractiveBoundsChanged?: (event: {
+    nativeEvent: {
+      selector: string;
+      left: number;
+      top: number;
+      right: number;
+      bottom: number;
+    };
+  }) => void;
+}
+
+const NativePylonChatView =
+  requireNativeComponent<NativePylonChatViewProps>("RNPylonChatView");
+
+const COMMANDS = {
+  openChat: "openChat",
+  closeChat: "closeChat",
+  showChatBubble: "showChatBubble",
+  hideChatBubble: "hideChatBubble",
+  showNewMessage: "showNewMessage",
+  setNewIssueCustomFields: "setNewIssueCustomFields",
+  setTicketFormFields: "setTicketFormFields",
+  updateEmailHash: "updateEmailHash",
+  showTicketForm: "showTicketForm",
+  showKnowledgeBaseArticle: "showKnowledgeBaseArticle",
+  clickElementAtSelector: "clickElementAtSelector",
+};
+
+export const PylonChatView = React.forwardRef<
+  PylonChatViewInternalRef,
+  PylonChatViewProps
+>(({ config, user, style, listener, topInset = 0 }, ref) => {
+  const nativeRef = useRef(null);
+
+  const dispatchCommand = (commandName: string, args: any[] = []) => {
+    const handle = findNodeHandle(nativeRef.current);
+    if (handle) {
+      UIManager.dispatchViewManagerCommand(handle, commandName, args);
+    }
+  };
+
+  // Expose imperative methods via ref
+  useImperativeHandle(
+    ref,
+    () => ({
+      openChat: () => dispatchCommand(COMMANDS.openChat),
+      closeChat: () => dispatchCommand(COMMANDS.closeChat),
+      showChatBubble: () => dispatchCommand(COMMANDS.showChatBubble),
+      hideChatBubble: () => dispatchCommand(COMMANDS.hideChatBubble),
+      showNewMessage: (message: string, isHtml = false) =>
+        dispatchCommand(COMMANDS.showNewMessage, [message, isHtml]),
+      setNewIssueCustomFields: (fields: Record<string, any>) =>
+        dispatchCommand(COMMANDS.setNewIssueCustomFields, [fields]),
+      setTicketFormFields: (fields: Record<string, any>) =>
+        dispatchCommand(COMMANDS.setTicketFormFields, [fields]),
+      updateEmailHash: (emailHash: string | null) =>
+        dispatchCommand(COMMANDS.updateEmailHash, [emailHash]),
+      showTicketForm: (slug: string) =>
+        dispatchCommand(COMMANDS.showTicketForm, [slug]),
+      showKnowledgeBaseArticle: (articleId: string) =>
+        dispatchCommand(COMMANDS.showKnowledgeBaseArticle, [articleId]),
+      clickElementAtSelector: (selector: string) =>
+        dispatchCommand(COMMANDS.clickElementAtSelector, [selector]),
+    }),
+    []
+  );
+
+  return (
+    <NativePylonChatView
+      ref={nativeRef}
+      style={style}
+      appId={config.appId}
+      widgetBaseUrl={config.widgetBaseUrl}
+      widgetScriptUrl={config.widgetScriptUrl}
+      enableLogging={config.enableLogging}
+      debugMode={config.debugMode}
+      primaryColor={config.primaryColor}
+      userEmail={user?.email}
+      userName={user?.name}
+      userAvatarUrl={user?.avatarUrl}
+      userEmailHash={user?.emailHash}
+      userAccountId={user?.accountId}
+      userAccountExternalId={user?.accountExternalId}
+      topInset={topInset}
+      onPylonLoaded={() => listener?.onPylonLoaded?.()}
+      onPylonInitialized={() => listener?.onPylonInitialized?.()}
+      onPylonReady={() => listener?.onPylonReady?.()}
+      onChatOpened={() => listener?.onChatOpened?.()}
+      onChatClosed={(event) =>
+        listener?.onChatClosed?.(event.nativeEvent.wasOpen)
+      }
+      onUnreadCountChanged={(event) =>
+        listener?.onUnreadCountChanged?.(event.nativeEvent.count)
+      }
+      onMessageReceived={(event) =>
+        listener?.onMessageReceived?.(event.nativeEvent.message)
+      }
+      onPylonError={(event) =>
+        listener?.onPylonError?.(event.nativeEvent.error)
+      }
+      onInteractiveBoundsChanged={(event) =>
+        listener?.onInteractiveBoundsChanged?.(event.nativeEvent)
+      }
+    />
+  );
+});
+
+PylonChatView.displayName = "PylonChatView";
+
+export default PylonChatView;

package/src/PylonChatWidget.android.tsx

@@ -0,0 +1,165 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "react";
+import { Pressable, StyleSheet, View } from "react-native";
+import type {
+  PylonChatViewInternalRef,
+  PylonChatViewRef,
+} from "./PylonChatView";
+import { PylonChatView } from "./PylonChatView";
+import type { PylonChatWidgetProps } from "./PylonChatWidget";
+import type { InteractiveBound } from "./types";
+
+/**
+ * Android implementation using proxy-based touch pass-through.
+ *
+ * State Management:
+ * - isChatOpen is ONLY set by native events (onChatOpened/onChatClosed)
+ * - Imperative methods (openChat/closeChat) call native, which then fires events
+ * - This ensures state is always synced with native layer
+ *
+ * Touch Pass-Through Strategy:
+ * 1. Native reports interactive element positions via onInteractiveBoundsChanged
+ * 2. React renders clickable Pressable views at those positions
+ * 3. When chat is closed: WebView has pointerEvents="none" (passes touches through)
+ * 4. Touches hit background OR proxy
+ * 5. Proxy clicked → calls openChat() → fires onChatOpened → state updates → WebView enabled
+ */
+export const PylonChatWidget = forwardRef<
+  PylonChatViewRef,
+  PylonChatWidgetProps
+>(({ config, user, listener, style, topInset }, ref) => {
+  // State synced ONLY via native events - single source of truth
+  // TODO: Consider useSyncExternalStore for a more resilient solution in the future.
+  const [isChatOpen, setIsChatOpen] = useState(false);
+  const [interactiveBounds, setInteractiveBounds] = useState<
+    InteractiveBound[]
+  >([]);
+
+  // Internal ref has additional methods not exposed to SDK users.
+  const chatRef = useRef<PylonChatViewInternalRef>(null);
+
+  // Forward ref methods - these call native, which fires events that update state
+  // CRITICAL: DO NOT set state directly here - let events handle it
+  useImperativeHandle(ref, () => ({
+    openChat: () => {
+      chatRef.current?.openChat();
+    },
+    closeChat: () => {
+      chatRef.current?.closeChat();
+    },
+    showChatBubble: () => chatRef.current?.showChatBubble(),
+    hideChatBubble: () => chatRef.current?.hideChatBubble(),
+    showNewMessage: (message: string, isHtml?: boolean) =>
+      chatRef.current?.showNewMessage(message, isHtml),
+    setNewIssueCustomFields: (fields: Record<string, any>) =>
+      chatRef.current?.setNewIssueCustomFields(fields),
+    setTicketFormFields: (fields: Record<string, any>) =>
+      chatRef.current?.setTicketFormFields(fields),
+    updateEmailHash: (emailHash: string | null) =>
+      chatRef.current?.updateEmailHash(emailHash),
+    showTicketForm: (slug: string) => chatRef.current?.showTicketForm(slug),
+    showKnowledgeBaseArticle: (articleId: string) =>
+      chatRef.current?.showKnowledgeBaseArticle(articleId),
+  }));
+
+  // CRITICAL: State is ONLY updated by these event handlers.
+  // The flow is: imperative method → native JS call → Pylon widget event → native callback → React event.
+  const handleChatOpened = useCallback(() => {
+    setIsChatOpen(true);
+    listener?.onChatOpened?.();
+  }, [listener]);
+
+  const handleChatClosed = useCallback(
+    (wasOpen: boolean) => {
+      setIsChatOpen(false);
+      listener?.onChatClosed?.(wasOpen);
+    },
+    [listener]
+  );
+
+  const handleBoundsChanged = useCallback((bounds: InteractiveBound) => {
+    setInteractiveBounds((prev) => {
+      const existing = prev.findIndex((b) => b.selector === bounds.selector);
+
+      // If bounds are 0,0,0,0 it means element is hidden - remove it
+      const isHidden =
+        bounds.left === 0 &&
+        bounds.top === 0 &&
+        bounds.right === 0 &&
+        bounds.bottom === 0;
+
+      if (existing >= 0) {
+        const updated = [...prev];
+        if (isHidden) {
+          updated.splice(existing, 1);
+        } else {
+          updated[existing] = bounds;
+        }
+        return updated;
+      }
+
+      if (isHidden) {
+        return prev;
+      }
+
+      return [...prev, bounds];
+    });
+  }, []);
+
+  const handleProxyPress = useCallback((selector: string) => {
+    // Trigger a click on the WebView element by its ID selector.
+    // This kind of only works for areas with a single clickable element.
+    // Really what htis needs to become is pass a coordinate to the webview, we look up whatever thing is at that
+    // coordinate, and click it. Which is very sophisticated and hacky.
+    chatRef.current?.clickElementAtSelector(selector);
+  }, []);
+
+  return (
+    <>
+      <View
+        style={[StyleSheet.absoluteFill, style]}
+        pointerEvents={isChatOpen ? "auto" : "none"}
+      >
+        {/* The actual WebView - disabled when chat is closed */}
+        <PylonChatView
+          ref={chatRef}
+          style={StyleSheet.absoluteFillObject}
+          config={config}
+          user={user}
+          topInset={topInset}
+          listener={{
+            ...listener,
+            onChatOpened: handleChatOpened,
+            onChatClosed: handleChatClosed,
+            onInteractiveBoundsChanged: handleBoundsChanged,
+          }}
+        />
+      </View>
+      {!isChatOpen &&
+        interactiveBounds.map((bounds, index) => (
+          <Pressable
+            key={`${bounds.selector}-${index}`}
+            style={{
+              position: "absolute",
+              left: bounds.left,
+              top: bounds.top,
+              width: bounds.right - bounds.left,
+              height: bounds.bottom - bounds.top,
+              backgroundColor:
+                __DEV__ && config.debugMode ? "rgba(0,255,0,0.2)" : undefined,
+              borderWidth: __DEV__ && config.debugMode ? 2 : 0,
+              borderColor: __DEV__ && config.debugMode ? "cyan" : undefined,
+            }}
+            onPress={() => handleProxyPress(bounds.selector)}
+          />
+        ))}
+    </>
+  );
+});
+
+PylonChatWidget.displayName = "PylonChatWidget";

package/src/PylonChatWidget.d.ts

@@ -0,0 +1,15 @@
+import { ViewStyle } from "react-native";
+import type { PylonChatViewRef } from "./PylonChatView";
+import type { PylonChatListener, PylonConfig, PylonUser } from "./types";
+
+export interface PylonChatWidgetProps {
+  config: PylonConfig;
+  user?: PylonUser;
+  listener?: PylonChatListener;
+  style?: ViewStyle;
+  topInset?: number;
+}
+
+export const PylonChatWidget: React.ForwardRefExoticComponent<
+  PylonChatWidgetProps & React.RefAttributes<PylonChatViewRef>
+>;