npm package: @maebgch/rcs-emulator
Description: A production-ready React component library for emulating RCS Business Messaging (RBM) device UI
Latest version: 0.1.14

# RCS Emulator React Package

Reusable, production-ready emulator UI for RCS Business Messaging (RBM). Ships as a React component with typed props, RBM JSON helpers, and bundled styles.

## Features

- Drop-in `RcsEmulator` component for RBM flows (light/dark themes, Android/iOS chrome)
- Accepts inline RBM JSON or fetches from a `jsonUrl`
- Emits structured `UserReplyPayload` callbacks for replies/actions (including WebView handling)
- Ships typed helpers and guards (`validateConversationFlow`, `useJsonFetch`, RBM schema types)
- Bundled CSS (`dist/style.css`) generated from Tailwind classes—no Tailwind setup required in consumer apps

## Installation

```bash
npm install @maebgch/rcs-emulator
# or
pnpm add @maebgch/rcs-emulator
# or
yarn add @maebgch/rcs-emulator
```

## Quick Start

```tsx
import {
  RcsEmulator,
  type RbmConversationFlow,
  type UserReplyPayload,
} from "@maebgch/rcs-emulator";
import "@maebgch/rcs-emulator/style.css";

const flow: RbmConversationFlow = {
  name: "Coffee Bot",
  conversation: [
    {
      id: "welcome",
      message: {
        text: "Welcome to Coffee Bot! Ready for a pick-me-up?",
      },
      suggestions: [
        {
          reply: { text: "Yes, show me options", postbackData: "coffee_yes" },
        },
        {
          reply: { text: "Maybe later", postbackData: "coffee_later" },
        },
      ],
      nextMessageIds: ["options", "bye"],
    },
    {
      id: "options",
      message: {
        richCard: {
          title: "Today's Specials",
          description: "Pick a drink to order",
          media: { url: "https://placehold.co/600x400", height: "medium" },
        },
      },
      suggestions: [
        { reply: { text: "Latte", postbackData: "latte" } },
        { reply: { text: "Cold Brew", postbackData: "cold_brew" } },
      ],
    },
    {
      id: "bye",
      message: { text: "No worries—text me anytime for coffee!" },
    },
  ],
};

export default function App() {
  const handleReply = (payload: UserReplyPayload) => {
    console.log("User interaction", payload);
  };

  return (
    <RcsEmulator
      messages={flow}
      onUserReply={handleReply}
      theme="light"
      device="android"
      showLockScreen={false}
    />
  );
}
```

## API Reference

### Props

- `messages?: RbmConversationFlow` – Inline RBM JSON (provide this OR `jsonUrl`)
- `jsonUrl?: string` – Remote RBM JSON to fetch
- `onUserReply: (payload: UserReplyPayload) => void` – Interaction callback
- `theme?: "light" | "dark"` – Default `light`
- `device?: "android" | "ios"` – Default `android`
- `businessInfo?: BusinessInfo` – Branding overrides (name, logo, brandColor, etc.)
- `className?: string` – Extra container classes
- `width?: number` / `height?: number` – Emulator frame size (defaults 375x667)
- `showSuggestions?: boolean` – Toggle suggestion chips
- `showLockScreen?: boolean` – Start on lock screen preview

### Callback Payload

`UserReplyPayload` includes `{ type: "reply" | "action", postbackData, displayText, actionData?, timestamp }`. WebView actions surface `actionData: { type: "webview", url, viewMode, description? }`.

### Additional Exports

- **Helpers:** `validateConversationFlow`, `getFirstMessagePreview`
- **Hooks:** `useJsonFetch`
- **RBM types & guards:** `RbmConversationFlow`, `RbmMessage`, `isSuggestedReply`, `isSuggestedAction`, `isWebViewAction`, `getWebViewConfig`
- **Standalone component:** `WebViewRenderer`

## RBM JSON Schema

- Use `RbmConversationFlow` type as the schema reference
- Each node supports text, rich cards, carousels, suggestions, and optional branching via `nextMessageIds`
- See TypeScript types in `src/components/RcsEmulator/types/rbm.types.ts` for full schema

## Usage Examples

### Basic Usage

```tsx
import { RcsEmulator } from "@maebgch/rcs-emulator";
import "@maebgch/rcs-emulator/style.css";

function App() {
  return (
    <RcsEmulator
      jsonUrl="https://example.com/conversation.json"
      onUserReply={(payload) => console.log(payload)}
    />
  );
}
```

### With Custom Theme and Device

```tsx
<RcsEmulator
  messages={conversationFlow}
  onUserReply={handleReply}
  theme="dark"
  device="ios"
  width={414}
  height={896}
/>
```

### With Business Branding

```tsx
<RcsEmulator
  messages={conversationFlow}
  onUserReply={handleReply}
  businessInfo={{
    name: "My Business",
    logo: "https://example.com/logo.png",
    brandColor: "#FF5733",
  }}
/>
```

## License

MIT