@tugitark/react-widget 1.0.0

package/Widget.tsx

@@ -0,0 +1,38 @@
+// Copyright (c) 2026, TugiTark.  All rights reserved.
+
+import * as React from 'react';
+import { useState } from 'react';
+
+import render, { Props } from '@tugitark/declarative-widget';
+
+function Widget(props: Props) {
+	// Is this the first time this component has been rendered ever?
+	const [firstTime, setFirstTime] = useState(true);
+
+	function onNotification(hasNotification: boolean) {
+		if (props.jwtFn == null && props.user == null) {
+			if (firstTime) {
+				// Replicate FAQ internal behaviour at a per-component level.
+				props.onNotification?.(hasNotification);
+			}
+		} else {
+			props.onNotification?.(hasNotification);
+		}
+	}
+
+	function onReady() {
+		if (firstTime) {
+			setFirstTime(false);
+			props.onReady?.();
+		}
+	}
+
+	render({ ...props, onReady, onNotification });
+
+	return (
+		<></>
+	);
+}
+
+export default Widget;
+

package/index.js

@@ -0,0 +1,7 @@
+// Copyright (c) 2026, TugiTark.  All rights reserved.
+
+/// <reference types="Widget" />
+
+import Widget from './Widget.tsx';
+export default Widget;
+

package/index.md

@@ -0,0 +1,148 @@
+ Tugi Tark React Widget Component
+==================================
+
+This library wraps the Tugi Tark chat widget in a standardised react component.  The component internally handles loading the latest version of the widget script from our CDN and translates between the imperative API controlling the widget and the react data flow model to configure things based purely on properties and callbacks.
+
+ Minimal Example
+-----------------
+
+This is the smallest number of properties that you can pass to `<TugiWidget>` and have it still operate correctly.
+
+```javascript
+import TugiWidget from '@tugitark/react-widget';
+
+function Component(props) {
+	return (
+		<TugiWidget
+			user={props.userId}
+			brandId="a040050697fc4b2db16acfbbad1d0da4"
+			brandName="Super Casino"
+			tenantId="gb-casinos-ltd"
+		/>
+	);
+}
+```
+
+If your server has the standard `/.tugi` endpoints (as provided by our back-end libraries and documented in our [developer documentation](https://gitlab.com/tugitark/integration/docs)) this is enough to get started with the Tugi Widget.  The `brandId`, `brandName`, and `tenantId` will be provided by us based on details provided by you when signing up with our system.  They are not secret, so can safely appear in client-side code, but are case-sensitive so must remain exactly as specified by us.
+
+`user` is the ID within your system of the current player.  How you determine the current player's unique ID depends entirely on your system and is left as a provided parameter here.  This is the ID that the widget will internally pass to the `/.tugi/jwt/issue` endpoint to retrieve the player's profile, and so must in some way identify an end-user on your server.
+
+ Custom Example
+----------------
+
+This is a more extensive widget example, with colour-scheme customisation and an explicit JWT lookup function.  The HTTP and websocket addresses are also specified, though match the defaults.
+
+```javascript
+import TugiWidget from '@tugitark/react-widget';
+
+interface Props {
+	getUserId: () => string;
+	isLoggedIn: () => boolean;
+};
+
+function Component(props: Props) {
+	async function jwtFn() {
+		if (!props.isLoggedIn()) {
+			return null;
+		}
+		const jwt = await fetch('/get-jwt-for-player/' + props.getUserId());
+		return jwt;
+	}
+
+	return (
+		<TugiWidget
+			jwtFn={jwtFn}
+			brandId="a040050697fc4b2db16acfbbad1d0da4"
+			brandName="Super Casino"
+			tenantId="gb-casinos-ltd"
+			httpUrl="https://app.tugi.ai/tugi.widget"
+			wsUrl="wss://ws.tugi.ai"
+			customize={{
+				title: 'Tugi Casino Help',
+				showTitle: true,
+				fontColor: '#2c3e50',
+				primaryColor: '#2c3e50',
+				secondaryColor: 'hsla(36, 100%, 50%, 1)',
+				homePageBackgroundColor: 'hsla(36, 100%, 37%, 0.2)',
+				homePageTextColor: '#2c3e50',
+			}}
+		/>
+	);
+}
+```
+
+ All Full Version Properties
+-----------------------------
+
+The full list of properties that can be passed to the `<TugiWidget>` component are:
+
+* `user` Optional.  When given will be used to look up a player's data from the server.  You can disable this automatic lookup by passing a custom `jwtFn` or by not passing the `user` parameter.  However, if you specify neither `user` nor `jwtFn` then the player will not be able to send any messages to Tugi Tark and you will get the free version of the widget instead (see below).
+* `jwtFn` Optional.  A function to override the default method for retrieving a player's data (via JWT).  While this and `user` are both optional, one of them must be specified.
+* `brandId` Required.  The ID of your brand, as provided by Tugi Tark.
+* `brandName` Required.  The name of your brand, as provided by you initially.
+* `tenantId` Required.  The ID of your company, as provided by Tugi Tark.
+* `language` Optional.  The player's language, for messages to be translated.
+* `httpUrl` Optional.  The address of the Tugi Tark backend to connect to.
+* `wsUrl` Optional.  The address of the Tugi Tark websocket to connect to.
+* `customize` Optional.  An object of CSS options for tweaking the visual appearance of the widget.  The complete set of configuration values in this object are documented elsewhere.
+* `onNotification` Optional.  An event callback triggered when a player recieves a new message.
+* `onReady` Optional.  An event callback triggered when the widget is fully initialised.
+* `onOpened` Optional.  An event callback triggered when the widget is opened up.
+* `onClosed` Optional.  An event callback triggered when the widget is hidden again.
+* `onError` Optional.  An event callback triggered when an error occurs.  If this is not given all errors are printed to the console.
+* `open` Optional.  When `true` the widget is forced to be open.  When `false` it is forced to be closed.  When not specified normal user control resumes.
+* `visible` Optional.  When `false` the widget can't be seen.
+
+The following two properties should all be specified together.  If either of them is missing then nothing will happen:
+
+* `proactiveMessage` Optional.  When specified will open a new ticket with this as the first message.  Requires `proactiveContext`.
+* `proactiveContext` Optional.  When specified will open a new ticket and pass this information to the backend as to why the ticket was created.  Requires `proactiveMessage`.
+* `ticketLanguageCode` Optional.  Can specify that the newly created ticket uses a different language to the widget language from `langauge`.
+
+A "proactive" message can be used to detect that a player has a problem and offer help without them needing to open a support ticket themselves.  `proactiveMessage` would contain a pleasant greeting for the player such as "Hi, we've noticed you're having some touble with your deposit, would you like to speak to one of our agents?", while `proactiveContext` actually contains the details of the detected error that needs solving, such as "£100 deposit from card **********3429 was rejected twice, at 18:43 and 19:11.  Error: Insufficient funds."
+
+ Free Version
+--------------
+
+If both `tugiFn` and `user` are missing from the `<TugiWidget>` properties then the widget goes in to the special free mode (more accurately, both must be `null` or `undefined` - if you want a user who isn't logged in pass a `user` of `''`).  In this mode the user cannot send or receive any messages, they can only view a few pre-defined FAQ-style help topics:
+
+```javascript
+import TugiWidget from '@tugitark/react-widget';
+
+function Component(props) {
+	return (
+		<TugiWidget
+			chatDisabledReason="You are not signed in."
+			title="FAQ"
+			body="Let us help you get started."
+			sections={[
+				{ title: 'Who are we?', content: 'We are Tugi Tark.' },
+				{ title: 'What do we do?', content: 'Make awesome customer support solutions.' },
+				{ title: 'How?', content: 'Smart AI agents who know all about your customers and services.' },
+				{ title: 'How do I join?', content: 'Click the sign-up botton at the top-right of the page.' },
+			]}
+		/>
+	);
+}
+```
+
+ All Free Version Properties
+-----------------------------
+
+* `chatDisabledReason` Required.  Why is this user not allowed to see the full chat widget, only this reduced version?
+* `title` Required.  What to put in the top bar of the widget.
+* `body` Required.  The main text to put in the widget.
+* `sections` Required.  An array of questions and answers (or other grouped data).  `title` is the "question", `content` is the "answer".
+
+The following optional properties are shared with the full version:
+
+* `customize`
+* `onNotification`
+* `onReady`
+* `onOpened`
+* `onClosed`
+* `onError`
+* `open`
+* `visible`
+
+

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@tugitark/react-widget",
+	"version": "1.0.0",
+	"description": "Wraps the tugitark widget in a React component.",
+	"scripts": {
+		"release": "npm publish --access public"
+	},
+	"files": [
+		"Widget.tsx",
+		"index.js",
+		"index.md"
+	],
+	"dependencies": {
+		"@tugitark/declarative-widget": "^1.0.0",
+		"react": ">=16.3.0"
+	},
+	"keywords": [
+		"Typescript",
+		"React",
+		"Tugitark",
+		"Casino",
+		"Integration",
+		"JWT",
+		"Library"
+	],
+	"author": "alex.cole@tugitark.com",
+	"license": "(c) 2026 Tugi Tark OÜ"
+}