@tugitark/react-widget 1.4.1 → 1.4.4

package/from-scratch.md

@@ -0,0 +1,86 @@
+ Reimplementing The Widget From Scratch
+========================================
+
+This library uses [@tugitark/declarative-widget](https://gitlab.com/tugitark/integration/libraries/javascript/declarative-widget) to handle the heavy lifting of detecting property changes, downloading the widget script, and (un)loading the actual widget tags on changes.  Basically that library converts the imperative and static Tugi Tark chat widget in to a functional equivalent.  All this library does is call that library from inside a component.
+
+The code below demonstrates the basics of what is going on behind the scenes within that library.  As detailed in [the original integration guide](https://www.tugitark.com/chat-setup), at some point the widget implementation must be imported using `<script>` and initialised via `window.tugiWidget.initialize()`.  This example handles those operations by dynamically loading the script via javascript, then calling the API method once the loading is completed.  The full version also handles unloading of the script for updates that cannot be applied after initialisation.  However, unloading the widget was never an intended operation and so how it is done uses several internal details that should not be replicated in your code, and will not br replicated here.
+
+ Steps
+=======
+
+* *Load the script*
+  
+  Create a `<script>` tag dynamically and inject it in to the page (if required):
+  
+  ```javascript
+  function loadScript() {
+      if (window.tugiWidget) {
+          // The script already exists.
+          initialise();
+          return;
+      }
+      const script = document.createElement('script');
+      // This attribute is recommended in the integration guide but may not work on `http` (testing).
+      //script.crossOrigin = 'anonymous';
+      script.async = true;
+      script.src = 'https://app.tugi.ai/tugi.widget/script';
+      script.onload = initialise;
+      script.onerror = (e) => console.error(e);
+      script.setAttribute('tugi-widget-script', 'true');
+      document.head.appendChild(script);
+  }
+  ```
+
+* *Initialise the widget*
+  
+  The details here are partially supplied by Tugi Tark (e.g. the `brandId`), and otherwise customisable by you:
+  
+  ```javacript
+  function initialise() {
+      window.tugiWidget.initialize({
+          jwtFn: getUserToken,
+          tenantId: 'gb-casinos-ltd',
+          brandId: 'a040050697fc4b2db16acfbbad1d0da4',
+          brandName: 'Super Casino',
+          httpUrl: 'https://app.tugi.ai/tugi.widget',
+          wsUrl: 'wss://ws.tugi.ai',
+          customize: {
+              title: 'Super Casino Chat',
+              showTitle: true,
+              fontColor: PRIMARY_COLOUR,
+              primaryColor: PRIMARY_COLOUR,
+              secondaryColor: 'hsla(36, 100%, 50%, 1)',
+              homePageBackgroundColor: 'hsla(36, 100%, 37%, 0.2)',
+              homePageTextColor: PRIMARY_COLOUR,
+          },
+      });
+  }
+  ```
+
+* *Request the JWT*
+  
+  This requires a user that is logged in:
+  
+  ```javacript
+  async function getUserToken() {
+      const response = await fetch('/users/current/tugi-token');
+      if (response.ok) {
+          const jwt = await response.text();
+          if (jwt !== '') return jwt;
+      }
+      return null;
+  }
+  ```
+  
+  Note that the standard endpoint for getting JWTs is `/.tugi/jwt/issue?id=<user-id>`.  The default code will use this endpoint if no `jwtFn` is supplied.
+
+* *Refesh the widget*
+  
+  If a user logs in after loading the widget tell it so it can update the JWT:
+  
+  ```javacript
+  if (window.tugiWidget?.isInitialized()) {
+      window.tugiWidget.refresh();
+  }
+  ```
+

package/index.md

@@ -3,10 +3,12 @@
 
 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.
 
+Also see [the original integration guide](https://www.tugitark.com/chat-setup) for more information about the widget itself.
+
  Minimal Example
 -----------------
 
-This is the smallest number of properties that you can pass to `<TugiWidget>` and have it still operate correctly.
+This is the smallest number of properties that you can pass to `<TugiWidget>` and have it still operate correctly.  These properties are given to you on signing up with Tugi Tark and must be entered accurately.
 
 ```javascript
 import TugiWidget from '@tugitark/react-widget';
@@ -150,7 +152,6 @@ The following optional properties are shared with the full version:
 
 While there can be only one widget on the page there can be multiple `<TugiWidget>` components at once.  Which one will be used is non-deterministic - even if you have one `<TugiWidget>` with `visible={true}` and another one with `visible={false}` this will not guarantee that the visible one is the one that gets shown, the invisible one may be "shown", resulting in neither being seen.  The one selected is based on internal render and update orders.  Further, having two at once may result in the widget being constantly unloaded and reloaded even when nothing has changed as the underlying code flips repeatedly between them.  If you have two versions of the widget shown in different circumstances then make sure that the whole component is conditional:
 
-
 ```javascript
 return (
 	disabled
@@ -185,3 +186,7 @@ return (
 	);
 ```
 
+[Click here](using-library.md) to see how this component wraps the underlying [@tugitark/declarative-widget](https://gitlab.com/tugitark/integration/libraries/javascript/declarative-widget) library in a react component.
+
+[Click here](from-scratch.md) to get a better understanding of everything that that library is doing behind the scenes to inject the main widget script in to a page and initialise it.
+

package/package.json

@@ -1,37 +1,39 @@
-{
-	"name": "@tugitark/react-widget",
-	"version": "1.4.1",
-	"description": "Wraps the tugitark widget in a React component.",
-	"scripts": {
-		"build": "npx esbuild index.ts --target=es6 --outfile=index.js && sed -i 's/\\bconst\\b/var/g' index.js && sed -i 's/\\blet\\b/var/g' index.js && npx esbuild index.js --allow-overwrite --minify --target=es5 --outfile=index.js && npx tsc --noErrorTruncation --declaration --emitDeclarationOnly --target es6 --module nodenext --moduleResolution nodenext --outDir . index.ts",
-		"release": "npm publish --access public",
-		"prerelease": "npm run build"
-	},
-	"files": [
-		"index.d.ts",
-		"index.js",
-		"index.md"
-	],
-	"dependencies": {
-		"@tugitark/declarative-widget": "^1.2.3"
-	},
-	"peerDependencies": {
-		"react": ">=0.0.0"
-	},
-	"devDependencies": {
-		"esbuild": "^0.27.2",
-		"react": "^19.2.3",
-		"typescript": "^5.9.3"
-	},
-	"keywords": [
-		"Typescript",
-		"React",
-		"Tugitark",
-		"Casino",
-		"Integration",
-		"JWT",
-		"Library"
-	],
-	"author": "alex.cole@tugitark.com",
-	"license": "(c) 2026 Tugi Tark OÜ"
-}
+{
+	"name": "@tugitark/react-widget",
+	"version": "1.4.4",
+	"description": "Wraps the tugitark widget in a React component.",
+	"scripts": {
+		"build": "npx esbuild index.ts --target=es6 --outfile=index.js && sed -i 's/\\bconst\\b/var/g' index.js && sed -i 's/\\blet\\b/var/g' index.js && npx esbuild index.js --allow-overwrite --minify --target=es5 --outfile=index.js && npx tsc --noErrorTruncation --declaration --emitDeclarationOnly --target es6 --module nodenext --moduleResolution nodenext --outDir . index.ts",
+		"release": "npm publish --access public",
+		"prerelease": "npm run build"
+	},
+	"files": [
+		"index.d.ts",
+		"index.js",
+		"index.md",
+		"using-library.md",
+		"from-scratch.md"
+	],
+	"dependencies": {
+		"@tugitark/declarative-widget": "^1.2.3"
+	},
+	"peerDependencies": {
+		"react": ">=0.0.0"
+	},
+	"devDependencies": {
+		"esbuild": "^0.27.2",
+		"react": "^19.2.3",
+		"typescript": "^5.9.3"
+	},
+	"keywords": [
+		"Typescript",
+		"React",
+		"Tugitark",
+		"Casino",
+		"Integration",
+		"JWT",
+		"Library"
+	],
+	"author": "alex.cole@tugitark.com",
+	"license": "(c) 2026 Tugi Tark OÜ"
+}

package/using-library.md

@@ -0,0 +1,18 @@
+ Reimplementing The Widget With A Library
+==========================================
+
+This library uses [@tugitark/declarative-widget](https://gitlab.com/tugitark/integration/libraries/javascript/declarative-widget) to handle the heavy lifting of detecting property changes, downloading the widget script, and (un)loading the actual widget tags on changes.  Basically that library converts the imperative and static Tugi Tark chat widget in to a functional equivalent.  All this library does is call that library from inside a component.
+
+The code below, while unoptimised, demonstrates how this compoment wraps that library.  See [the source code](index.ts) for more details.
+
+```typescript
+import render, { type Props } from '@tugitark/declarative-widget';
+
+export default function TugiWidget(props: Props) {
+	render(props);
+	return null;
+}
+```
+
+The full version contains a few additional checks to ensure that certain events are only triggered once per component instance.  But other than that, this is essentially all there is to this wrapper.  All the complexities of reloading and updating the actual widget implementation itself are handled in the *declarative-widget* library itself.  See [the from-scratch example](from-scratch.md) for a deeper explanation of what is happening behind the scenes in that library.
+