@zean-chat/js 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @zean-chat/js: live chat widget for any website
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add a free customer support chat to your website in one line, with [Zean](https://zean.chat/?utm_source=npm&utm_medium=readme&utm_campaign=js). Plain JavaScript or TypeScript, any framework or none. Your App key is in your Zean dashboard.
+
+```bash
+npm install @zean-chat/js
+```
+
+```js
+import { loadZean } from "@zean-chat/js";
+
+const zean = loadZean({ appKey: "app_your_app_key" });
+zean.open();
+zean.onUnreadChange(count => console.log(count));
+```
+
+Methods: `open`, `close`, `toggle`, `getUnreadCount`, `onUnreadChange`, `identify(getToken)`, `signOut`, `setAttributes`. They can be called before the chat has loaded. Full guide: [install the chat on a website](https://zean.chat/docs/install-website), [JavaScript reference](https://zean.chat/docs/reference-js).
+
+## Why Zean
+
+- Free plan to start. Paid plans in FCFA, payable by Mobile Money.
+- Shared inbox for your team. Reply from your phone.
+- Verified identity, webhooks, French and English. Fast even on 3G.
+
+## Links
+
+[Zean live chat](https://zean.chat/?utm_source=npm&utm_medium=readme&utm_campaign=js) · [Documentation](https://zean.chat/docs) · [Create a free account](https://zean.chat/sign-in?utm_source=npm&utm_medium=readme&utm_campaign=js) · [Zean vs Intercom](https://zean.chat/compare/intercom) · [Zean vs Crisp](https://zean.chat/compare/crisp)
+
+Other SDKs: [@zean-chat/js](https://www.npmjs.com/package/@zean-chat/js) · [@zean-chat/react](https://www.npmjs.com/package/@zean-chat/react) · [@zean-chat/vue](https://www.npmjs.com/package/@zean-chat/vue) · [@zean-chat/react-native](https://www.npmjs.com/package/@zean-chat/react-native)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { ZeanApi, ZeanAttributeValue, ZeanAttributes, ZeanLocale, ZeanOptions, ZeanSettings, ZeanTokenSource } from './interfaces.js';
+export { loadZean, zean } from './load.js';

package/dist/index.js

@@ -0,0 +1,78 @@
+// ../shared/src/constants/app.ts
+var APP_NAME = "Zean";
+var PRODUCTION_LOADER_URL = "https://widget.zean.chat/loader.js";
+
+// src/load.ts
+var SCRIPT_ATTRIBUTE = "data-zean-sdk";
+var OTHER_LOADER_CHECKS = 300;
+var loadedKey = null;
+var waiting = [];
+var readyApi = () => {
+  const current = typeof window === "undefined" ? void 0 : window.zean;
+  return typeof current?.open === "function" ? current : null;
+};
+var withApi = (call) => {
+  const api = readyApi();
+  if (api) call(api);
+  else if (typeof window !== "undefined") waiting.push(call);
+};
+var flush = () => {
+  const api = readyApi();
+  if (api) for (const call of waiting.splice(0)) call(api);
+};
+var waitForOtherLoader = () => {
+  let checks = 0;
+  const timer = window.setInterval(() => {
+    checks += 1;
+    if (readyApi() || checks >= OTHER_LOADER_CHECKS) window.clearInterval(timer);
+    flush();
+  }, 100);
+};
+var zean = {
+  open: () => withApi((api) => api.open()),
+  close: () => withApi((api) => api.close()),
+  toggle: () => withApi((api) => api.toggle()),
+  getUnreadCount: () => readyApi()?.getUnreadCount() ?? 0,
+  onUnreadChange(listener) {
+    let stop = null;
+    let stopped = false;
+    withApi((api) => {
+      if (!stopped) stop = api.onUnreadChange(listener);
+    });
+    return () => {
+      stopped = true;
+      stop?.();
+    };
+  },
+  identify: (getToken) => withApi((api) => api.identify(getToken)),
+  signOut: () => withApi((api) => api.signOut()),
+  setAttributes: (attributes) => withApi((api) => api.setAttributes(attributes))
+};
+function loadZean({ appKey, getToken, locale, loaderUrl = PRODUCTION_LOADER_URL }) {
+  if (typeof window === "undefined" || typeof document === "undefined") return zean;
+  if (loadedKey !== null) {
+    if (loadedKey !== appKey) console.warn(`${APP_NAME}: the chat is already loaded with the App key ${loadedKey}.`);
+    return zean;
+  }
+  loadedKey = appKey;
+  if (window.zean || document.querySelector(`script[${SCRIPT_ATTRIBUTE}]`)) {
+    waitForOtherLoader();
+    if (getToken) zean.identify(getToken);
+    return zean;
+  }
+  window.zean = { appKey, ...getToken ? { getToken } : {}, ...locale ? { locale } : {} };
+  const script = document.createElement("script");
+  script.async = true;
+  script.src = loaderUrl;
+  script.setAttribute(SCRIPT_ATTRIBUTE, "");
+  script.addEventListener("load", flush);
+  script.addEventListener("error", () => console.error(`${APP_NAME}: the chat could not load from ${loaderUrl}.`), {
+    once: true
+  });
+  document.head.appendChild(script);
+  return zean;
+}
+export {
+  loadZean,
+  zean
+};

package/dist/interfaces.d.ts

@@ -0,0 +1,33 @@
+/** Returns a token the Company's server signed for the signed-in person, or null when there is none. */
+export type ZeanTokenSource = () => Promise<string | null>;
+export type ZeanAttributeValue = string | number | boolean;
+/** What the page knows about the person, shown on the Contact's profile: `{ city: 'Douala', orders: 12 }`. */
+export type ZeanAttributes = Record<string, ZeanAttributeValue>;
+export type ZeanLocale = 'fr' | 'en';
+/** What `window.zean` holds before the loader runs: the install code sets it. */
+export interface ZeanSettings {
+    appKey: string;
+    /** For a signed-in person. Same as calling `identify` once loaded. */
+    getToken?: ZeanTokenSource;
+    /** The chat's language. Leave it out: the Contact's browser's, when the chat speaks it, else the App's default. */
+    locale?: ZeanLocale;
+}
+/** The chat's methods, on `window.zean` once the loader has run. */
+export interface ZeanApi {
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    getUnreadCount: () => number;
+    /** Called with each new count of replies the Contact has not seen. Returns the way to stop. */
+    onUnreadChange: (listener: (count: number) => void) => () => void;
+    /** The person signed in: `getToken` is called now and whenever the token expires. */
+    identify: (getToken: ZeanTokenSource) => void;
+    /** The person signed out: the chat starts over, anonymous. */
+    signOut: () => void;
+    /** Joined to what was set before. Values the chat cannot keep are refused, and the console says why. */
+    setAttributes: (attributes: ZeanAttributes) => void;
+}
+export interface ZeanOptions extends ZeanSettings {
+    /** Where the chat loads from. Leave it out: the default is Zean's own. */
+    loaderUrl?: string;
+}

package/dist/load.d.ts

@@ -0,0 +1,13 @@
+import type { ZeanApi, ZeanOptions, ZeanSettings } from './interfaces.js';
+declare global {
+    interface Window {
+        zean?: ZeanSettings & Partial<ZeanApi>;
+    }
+}
+/** The chat's methods. Usable before `loadZean`: what is asked waits for the chat. */
+export declare const zean: ZeanApi;
+/**
+ * Shows the chat on the page: adds the hosted loader once, whatever the number of calls. Does nothing on the server,
+ * so it is safe in code that also renders there.
+ */
+export declare function loadZean({ appKey, getToken, locale, loaderUrl }: ZeanOptions): ZeanApi;

package/package.json

@@ -1,6 +1,64 @@
 {
-  "name": "@zean-chat/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@zean-chat/js",
+	"version": "0.1.1",
+	"description": "Live chat widget for any website: add a free customer support chat in one line. Vanilla JS, TypeScript, no framework needed. Intercom and Crisp alternative.",
+	"keywords": [
+		"javascript",
+		"typescript",
+		"vanilla-js",
+		"website-chat",
+		"chat-bubble",
+		"sdk",
+		"live-chat",
+		"chat-widget",
+		"support-chat",
+		"customer-support",
+		"customer-service",
+		"helpdesk",
+		"help-desk",
+		"in-app-chat",
+		"chat",
+		"messaging",
+		"zean",
+		"intercom-alternative",
+		"crisp-alternative",
+		"tawk-to-alternative",
+		"zendesk-alternative"
+	],
+	"homepage": "https://zean.chat/docs/install-website",
+	"bugs": {
+		"url": "https://zean.chat/contact"
+	},
+	"author": "Zean (https://zean.chat)",
+	"license": "MIT",
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"zean-source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"prepublishOnly": "npm run build",
+		"build": "node ../../scripts/build-sdk.mjs",
+		"check-types": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@zean/config": "*",
+		"@zean/shared": "*",
+		"happy-dom": "21.0.3",
+		"typescript": "6.0.3",
+		"vitest": "4.1.11"
+	}
+}