@askly/widget 2.2.1 → 2.3.1

package/README.md

@@ -15,51 +15,38 @@ Askly is an **embeddable AI support chat widget** for React and plain HTML. Drop
 - 📚 **RAG (docs-grounded)** — replies grounded in your own documentation, not hallucinated.
 - 🎙️ **Voice chat** — customers can talk to the assistant, not just type.
 - 🙋 **Human handoff** — one-click escalation to a live agent when needed.
-- ⚛️ **React + CDN** — use as an npm module or a single `<script>` tag.
+- ⚛️ **React + CDN** — use as an npm module, or a single `<script>` tag on any site (no React required).
 - 🎨 **Fully themeable** — colors, logo, position, and copy configured in the portal.
 
 ## Installation
 
-### NPM
-```bash
-npm install @askly/widget
-```
+### Script tag (any website)
 
-### CDN
-Include the UMD build directly in your HTML:
-```html
-<!-- React Dependencies -->
-<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
-<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+One line, before `</body>`. The bundle is self-contained — no React or other dependencies on your page:
 
-<!-- Askly SDK -->
-<script src="https://unpkg.com/@askly/widget@latest/dist/index.umd.js"></script>
+```html
+<script src="https://unpkg.com/@askly/widget@latest/dist/widget.js" data-app-id="YOUR_APP_ID" async></script>
 ```
 
-## Quick Start
+That's the whole install. Your branding — name, logo, theme, welcome message — loads automatically from your Askly portal settings.
 
-All you need is your `widgetId` — copy it from the **Widget setup** screen in your Askly tenant portal. Everything else (name, theme, logo, welcome message, voice, etc.) is configured there and loaded automatically; the init props below are optional overrides.
+### NPM (React / bundlers)
+
+```bash
+npm install @askly/widget
+```
 
 ```javascript
 import Askly from '@askly/widget';
 
-Askly.init({ widgetId: "your-widget-id" });
+Askly.init({ appId: "YOUR_APP_ID" });
 ```
 
-For CDN initialization:
-```html
-<script>
-  Askly.init({ widgetId: "your-widget-id" });
-</script>
-```
+The npm builds (`index.esm.js` / `index.umd.js`) treat React as a peer dependency, so your bundle isn't double-shipping it.
 
-Alternatively, initialize automatically via a single script tag:
-```html
-<script
-  src="https://unpkg.com/@askly/widget@latest/dist/index.umd.js"
-  data-widget-id="your-widget-id"
-></script>
-```
+## Quick Start
+
+All you need is your `appId` — copy it from **Widget → Install Code** in your Askly tenant portal. Everything else (name, theme, logo, welcome message, voice, etc.) is configured there and loaded automatically; the init props below are optional overrides.
 
 > The widget talks to Askly's hosted backend automatically — there is nothing else to configure.
 
@@ -69,11 +56,13 @@ The `Askly.init()` method accepts an object with the following configuration opt
 
 | Option | Type | Required | Default | Description |
 | :--- | :--- | :--- | :--- | :--- |
-| `widgetId` | `string` | **Yes** | - | Your widget ID, from the tenant portal's Widget setup screen. |
+| `appId` | `string` | **Yes** | - | Your app ID, from the tenant portal's **Widget → Install Code** screen. Script tag: `data-app-id`. |
+
+> `widgetId` and `orgId` are still accepted as deprecated aliases for `appId`, so existing embeds keep working.
 
 ### Configured in the portal
 
-The widget's appearance and behaviour — display name, logo, theme color, welcome message, position, voice, sounds, timestamps, "powered by" text, and so on — are set on the **Widget setup** screen in your Askly portal and loaded automatically by `widgetId`. **You do not pass these in code.** (They remain accepted as optional `init()` overrides for advanced cases, but the portal is the source of truth.)
+The widget's appearance and behaviour — display name, logo, theme color, welcome message, position, voice, sounds, timestamps, "powered by" text, and so on — are set on the **Widget** screen in your Askly portal and loaded automatically by `appId`. Logos are uploaded right there and apply instantly. **You do not pass these in code.** (They remain accepted as optional `init()` overrides for advanced cases, but the portal is the source of truth.)
 
 ### Identifying an authenticated user
 
@@ -151,10 +140,10 @@ Control where the widget appears using URL **path prefixes** (matched against `w
 
 ```javascript
 // Show ONLY on support & docs pages
-Askly.init({ widgetId: "your-widget-id", includePaths: ["/support", "/docs"] });
+Askly.init({ appId: "YOUR_APP_ID", includePaths: ["/support", "/docs"] });
 
 // Show everywhere EXCEPT admin & checkout
-Askly.init({ widgetId: "your-widget-id", excludePaths: ["/admin", "/checkout"] });
+Askly.init({ appId: "YOUR_APP_ID", excludePaths: ["/admin", "/checkout"] });
 ```
 
 Via script tag, use comma-separated values: `data-include-paths="/support,/docs"` or `data-exclude-paths="/admin,/checkout"`.
@@ -172,7 +161,7 @@ Callbacks are functions, so they can only be attached in code (not from the port
 
 ```javascript
 Askly.init({
-  widgetId: "your-widget-id",
+  appId: "YOUR_APP_ID",
   onMessageSent: (message) => console.log("Sent:", message),
   onMessageReceived: (reply) => console.log("Received:", reply),
   onChatOpened: () => console.log("Opened"),
@@ -183,7 +172,7 @@ Askly.init({
 
 ## Backend Integration
 
-None required. The widget talks to Askly's hosted backend automatically — you only provide a `widgetId`.
+None required. The widget talks to Askly's hosted backend automatically — you only provide an `appId`.
 
 ## Development
 
@@ -195,6 +184,25 @@ npm install
 npm run build
 ```
 
+### Releasing
+
+```bash
+npm version <patch|minor|major>
+npm publish            # prepublishOnly rebuilds dist/
+```
+
+**Publishing is not the last step.** The tenant portal bundles this package
+(`AsklyWidget.tsx` and the help centre both `import("@askly/widget")`), and its Docker build runs
+`npm ci` — which installs whatever `package-lock.json` pins and ignores the `^` range entirely. So
+a new version does not reach Askly's own site until the portal's lockfile is bumped:
+
+```bash
+cd ../tenant-portal && npm install @askly/widget@latest   # updates package-lock.json
+```
+
+Skipping this is how 2.2.0 shipped to npm while the portal kept serving 2.1.0 for a day — visitors
+were unrecognisable there, and every message showed as a separate person in the Inbox.
+
 ## Why Askly?
 
 **Is this an AI customer support widget I can embed in React?**

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type AsklyIdentity } from "./identity";
 export interface AsklyConfig {
+    appId?: string;
     widgetId?: string;
     orgId?: string;
     orgServerRoute?: string;
@@ -62,5 +63,11 @@ declare const Askly: {
     reset: () => void;
     /** Remove the widget from the page. Also resets identity, as on logout. */
     shutdown: () => void;
+    /** Open the chat panel — for host-page CTAs like a "Contact us" button. */
+    open: () => void;
+    /** Close the chat panel. */
+    close: () => void;
+    /** Toggle the chat panel. */
+    toggle: () => void;
 };
 export default Askly;