@bridge-ai-dev/ecom-chat

v1.1.3

Published

8 days ago

Bridge E-commerce Chat widget integration for Next.js with Litium authentication

0High
0Medium
0Low

sreelakshmi.bridge

bridge-chat litium nextjs react authentication chat-widget

Bridge E-commerce Chat widget integration for Next.js

A powerful chat widget integration specifically designed for Next.js and Litium storefronts. It handles complex authentication flows and automatic cart context initialization.

Features

Automatic Cart Scaling: Server-side cart creation using Litium's CreateCart mutation.
Secure Auth Bridge: Handles HttpOnly cookies (.AspNetCore.Identity.Application and cart-context) safely.
Next.js Optimized: Built for the App Router and React Server Components.
Zero Configuration: Scaffolding tool to get you started in seconds.

Quick Start

Run the following command in your Next.js project root:

npx @bridge-ai-dev/ecom-chat

This will:

Create app/api/bridge-auth/route.ts (The secure auth bridge)
Create components/ChatWrapper.tsx (A pre-configured component wrapper)

Configuration

Add the following environment variables to your .env.local:

# Required for the Widget
NEXT_PUBLIC_BRIDGE_TENANT_ID=your-tenant-uuid
NEXT_PUBLIC_BRIDGE_WIDGET_URL=https://...

# Required for server-side cart initialization
RUNTIME_LITIUM_SERVER_URL=https://your-litium-backend.com

Ecom Chat - UI

Bridge E-commerce Chat widget integration for Next.js with Litium authentication.

This package provides React components to easily integrate the Bridge Chat widget into your Next.js ecommerce storefront. It securely handles the authentication handshake between your storefront's HttpOnly cookies and the Bridge Chat application.

Prerequisites

Next.js 13+ with App Router
React 17 or higher

Installation

Install the package via npm:

npm install @bridge-ai-dev/ecom-chat

Setup

The chat components require a server-side API route to retrieve secure HttpOnly cookies (like cart-context and ASP.NET Core Identity cookies) that are inaccessible from client-side JavaScript.

To automatically generate this API route and a wrapper component in your Next.js app, run:

npx create-ecom-chat

This will create:

An API route at app/api/bridge-auth/route.ts.
A React wrapper component at components/ChatWrapper.tsx.

Usage

In your app/layout.tsx:

import ChatWrapper from '@/components/ChatWrapper';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <ChatWrapper />
      </body>
    </html>
  );
}

How it works

The library uses a "Bridge Auth" pattern:

The ChatComponent (client-side) calls the /api/bridge-auth route.
The Auth Route (server-side) reads the secure Litium cookies.
If the cart-context cookie is missing, the route automatically performs a CreateCart mutation to Litium's GraphQL API.
The route returns the auth data to the widget and forwards any new Set-Cookie headers to the browser.

Customization

`ChatComponent` Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | tenantId | string | Required | Your Bridge AI tenant ID. | | widgetScriptUrl | string | Required | URL of the chat widget script. | | cartCreationMode | 'server' \| 'client' \| 'none' | 'server' | How to handle missing carts. |

You can include the generic ChatComponent directly in your application, or use the CLI-generated ChatWrapper for a cleaner integration.

Method 1: Using the Generated Wrapper (Recommended for Litium)

If you used npx create-ecom-chat, a ChatWrapper.tsx file was generated for you. It uses environment variables to access your Bridge tenant ID and widget script URL.

First, add the following variables to your .env.local or .env file:

NEXT_PUBLIC_BRIDGE_TENANT_ID=your-tenant-uuid
NEXT_PUBLIC_BRIDGE_WIDGET_URL=https://your-cdn.com/chat-widget.js

Then, simply drop the generated component into your root layout (app/layout.tsx):

import ChatWrapper from '@/components/ChatWrapper';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <ChatWrapper />
      </body>
    </html>
  );
}

Method 2: Standard Usage (`ChatComponent`)

If you prefer to integrate the component manually without the wrapper, you can import and use ChatComponent directly in any client component:

'use client';

import { ChatComponent } from '@bridge-ai-dev/ecom-chat';
import { get } from '@/services/cartService.client'; // Adjust path to your project's fetching function

export default function ChatWrapper() {
  return (
    <ChatComponent
      tenantId={process.env.NEXT_PUBLIC_BRIDGE_TENANT_ID || ""}
      widgetScriptUrl={process.env.NEXT_PUBLIC_BRIDGE_WIDGET_URL}
      getCartFunction={get}
    />
  );
}

API Reference

Component Properties

ChatComponent accepts the following properties:

Required

tenantId (string): The unique tenant identifier for your Bridge Chat instance.

Optional Configuration

widgetScriptUrl (string): URL to dynamically load the chat widget script if not already included in your HTML.
getCartFunction (() => Promise<any>): Function to call the API from the client side when the cart-context cookie is missing. The component will trigger this function to create the cart and then read the locally updated cookies.
bridgeAuthEndpoint (string): Custom API endpoint for the bridge auth route. Default is '/api/bridge-auth'.
containerId (string): Custom ID for the chat container div. Default is 'bgc-chat-container'.

Widget Customization

position (WidgetPosition): Screen position. Default 'bottom-right'.
backgroundColor (string): Widget background color. Default '#6366f1'.
foregroundColor (string): Widget text color. Default '#ffffff'.
size (WidgetSize): Widget size ('small' | 'medium' | 'large'). Default 'medium'.
borderWidth (number): Widget border width in pixels. Default 2.
borderColor (string): Widget border color. Default '#4f46e5'.
autoPopup (boolean): Automatically open the chat widget on load. Default false.

Callbacks

onAuthSuccess ((authData: BridgeAuthResponse) => void): Callback when the authentication bridge completes successfully.
onAuthError ((error: Error) => void): Callback when the authentication bridge fails.

Auth Bypass

If provided, these properties will bypass the internal bridge-auth API call completely.

cartContext (string): Hardcode a specific cart context token.
identity (string): Hardcode a specific identity token.

Types

You can import types directly from the package:

import type {
    ChatComponentProps,
    BridgeAuthResponse,
    BridgeChatInitConfig,
    BridgeChatGlobal,
    WidgetPosition,
    WidgetSize
} from '@bridge-ai-dev/ecom-chat';

License

MIT MIT