@dinghy-chat/widget 0.0.0-stage → 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dinghy contributors
+
+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,82 @@
-# Temporary Holding Version
+# Dinghy widget
 
-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.
+The chat widget for [Dinghy](https://dinghy.chat), a small live support chat you can host yourself. MIT licensed.
+
+## Add it with a tag
+
+```html
+<script src="https://chat.example.com/widget/loader.js" data-key="YOUR_PUBLIC_KEY" async></script>
+```
+
+## Or add it from npm
+
+```sh
+npm install @dinghy-chat/widget
+```
+
+```ts
+import { init } from "@dinghy-chat/widget";
+
+const dinghy = init({ url: "https://chat.example.com", key: "YOUR_PUBLIC_KEY" });
+dinghy.on("unread", (count) => console.log(count));
+```
+
+`init` adds the tag once and returns the typed `Dinghy` object. Calls made before the script loads wait for it. It takes `url`, `key`, and `primary`, `accent`, `mascot`, `launcher`, `position`, `offsetX`, `offsetY` and `zIndex`.
+
+## Attributes
+
+| Attribute                | Effect                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------- |
+| `data-primary="#0b2239"` | Sets the header, your visitor's messages and the boat's hull. Use six hex digits.           |
+| `data-accent="#e5352b"`  | Sets the sail and the send button, and the launcher if the boat is off. Use six hex digits. |
+| `data-mascot="false"`    | Removes the boat. Every state keeps its text.                                               |
+| `data-launcher="hidden"` | Hides the launcher, so your own button opens the chat.                                      |
+| `data-position="left"`   | Puts the launcher and the chat on the left. The default is `right`.                         |
+| `data-offset-x="24"`     | Pixels from the side of the window. The default is `16`.                                    |
+| `data-offset-y="80"`     | Pixels from the bottom of the window. The default is `16`.                                  |
+
+The widget ignores a value in any other format. The boat stops moving for a visitor who asks for reduced motion.
+
+Set `--dinghy-font`, `--dinghy-radius` and `--dinghy-launcher-radius` on the `dinghy-chat` element to match your fonts and corners.
+
+## Host page API
+
+| Call                                | What it does                                                                                                    |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `Dinghy.open({ message })`          | Opens the chat. `message` is optional and fills the message box without sending it                              |
+| `Dinghy.close()`, `Dinghy.toggle()` | Closes the chat, or opens it if it is closed                                                                    |
+| `Dinghy.show()`, `Dinghy.hide()`    | Shows or hides the launcher                                                                                     |
+| `Dinghy.identify(token)`            | Signs in a user. `token` is a string, or a function that returns a promise of one, so a tab can renew a token   |
+| `Dinghy.reset()`                    | Ends the session in all tabs. Call this at sign-out                                                             |
+| `Dinghy.setContext(data)`           | Unsigned facts for operators, such as a plan. Up to 20 keys, each a short string, a number, a boolean or `null` |
+| `Dinghy.configure(options)`         | Changes `primary`, `accent`, `position`, `offsetX`, `offsetY` and `zIndex` now                                  |
+| `Dinghy.on(event, callback)`        | Calls `callback` on each event, and returns a function that removes it                                          |
+| `Dinghy.state`                      | `{ ready, open, unread }`                                                                                       |
+
+The events are `ready`, `open`, `close`, `unread` (the count, at once and on each change), `message:sent` and `message:received` (`{ body }`) and `conversation:started`.
+
+To call these before the loader finishes, queue them:
+
+```html
+<script>window.Dinghy = { q: [["identify", "TOKEN"], ["on", "unread", console.log]] };</script>
+```
+
+Your backend signs the token with HS256 and the workspace's signing secret. It needs `sub` (your user ID), `aud` (the public key), `iat`, and `exp` at most 24 hours later. `email`, `name` (one line, up to 100 characters) and `attributes` (an object up to 2 KB) are optional, and operators read them.
+
+The widget stores nothing in the browser until the visitor sends a message, and then only its own token in `localStorage`. While such a visitor has the chat open, it notes that in `sessionStorage`, so the chat opens again after a reload in the same tab. Once the visitor has chatted, it reports the page's address, without its query string or `#` part, its title and the `setContext` data, so operators see where the visitor is.
+
+## Content Security Policy
+
+If your site sets a CSP, add the origin of your Dinghy server to these directives:
+
+```
+script-src https://chat.example.com;
+connect-src https://chat.example.com;
+img-src https://chat.example.com;
+```
+
+If your Dinghy serves images from a separate origin (`IMAGES_ORIGIN`), allow that origin in `img-src` too.
+
+The widget needs no `style-src` change, because it uses constructable stylesheets and the CSSOM.
+
+The full guide is at <https://dinghy.chat/docs/add-to-your-site>.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { Appearance, DinghyApi } from "./shared.ts";
+export type { Appearance, DinghyApi, DinghyEvent, DinghyEvents, DinghyState, Identity, OpenOptions, PageContext, } from "./shared.ts";
+export interface InitOptions extends Appearance {
+    /** Your Dinghy server, such as `https://chat.example.com`. */
+    url: string;
+    /** The workspace's public key, from Settings > Widget snippet. */
+    key: string;
+    /** False removes the boat. Every state keeps its text. */
+    mascot?: boolean;
+    /** False hides the launcher, so your own button opens the chat. */
+    launcher?: boolean;
+}
+/** The same `Dinghy` as the loader's, usable before the loader runs. */
+export declare const Dinghy: DinghyApi;
+/**
+ * Adds the chat to the page once, and returns `Dinghy`. A second call returns the same object and
+ * adds nothing. On a server, with no document, it only returns `Dinghy`.
+ */
+export declare function init(options: InitOptions): DinghyApi;

package/dist/index.js

@@ -0,0 +1,75 @@
+// src/index.ts
+var slot = globalThis;
+function loaded() {
+  const current = slot.Dinghy;
+  return current !== void 0 && "on" in current ? current : void 0;
+}
+function enqueue(call) {
+  const queue = slot.Dinghy ?? {};
+  queue.q = [...queue.q ?? [], call];
+  slot.Dinghy = queue;
+}
+function forward(method, ...args) {
+  const api = loaded();
+  if (api === void 0) enqueue([method, ...args]);
+  else api[method](...args);
+}
+var NOT_READY = { ready: false, open: false, unread: 0 };
+var Dinghy = {
+  open: (options) => forward("open", ...options === void 0 ? [] : [options]),
+  close: () => forward("close"),
+  toggle: () => forward("toggle"),
+  show: () => forward("show"),
+  hide: () => forward("hide"),
+  identify: (identity) => forward("identify", identity),
+  reset: () => forward("reset"),
+  setContext: (data) => forward("setContext", data),
+  configure: (options) => forward("configure", options),
+  on(event, callback) {
+    let active = true;
+    const listener = (data) => {
+      if (active) callback(data);
+    };
+    const api = loaded();
+    let off;
+    if (api === void 0) enqueue(["on", event, listener]);
+    else off = api.on(event, listener);
+    return () => {
+      active = false;
+      off?.();
+    };
+  },
+  get state() {
+    return loaded()?.state ?? { ...NOT_READY };
+  }
+};
+var added = false;
+function init(options) {
+  if (added || typeof document === "undefined") return Dinghy;
+  added = true;
+  const base = options.url.endsWith("/") ? options.url : `${options.url}/`;
+  const script = document.createElement("script");
+  script.src = new URL("widget/loader.js", base).href;
+  script.async = true;
+  const attributes = [
+    ["key", options.key],
+    ["primary", options.primary],
+    ["accent", options.accent],
+    ["position", options.position],
+    ["offset-x", options.offsetX],
+    ["offset-y", options.offsetY],
+    ["mascot", options.mascot === false ? "false" : void 0],
+    ["launcher", options.launcher === false ? "hidden" : void 0]
+  ];
+  for (const [name, value] of attributes) {
+    if (value !== void 0) script.setAttribute(`data-${name}`, String(value));
+  }
+  if (options.zIndex !== void 0) Dinghy.configure({ zIndex: options.zIndex });
+  slot.Dinghy ??= { q: [] };
+  document.head.append(script);
+  return Dinghy;
+}
+export {
+  Dinghy,
+  init
+};

package/dist/shared.d.ts

@@ -0,0 +1,106 @@
+/** A signed token from the host backend, or a function that fetches a new one. */
+export type Identity = string | (() => Promise<string>);
+/** Unsigned facts from the page, such as a plan or a cart total. Operators see them as unverified. */
+export type PageContext = Record<string, string | number | boolean | null>;
+export interface OpenOptions {
+    /** Fills the message box. The visitor still sends it. */
+    message?: string;
+}
+/** What `configure` and the script tag's data attributes change. Invalid values are ignored. */
+export interface Appearance {
+    /** A six-digit hex color, such as `#0b2239`. */
+    primary?: string;
+    accent?: string;
+    position?: "left" | "right";
+    /** Pixels from the side and from the bottom of the window, 0 to 1000. */
+    offsetX?: number;
+    offsetY?: number;
+    zIndex?: number;
+}
+export interface DinghyState {
+    /** The chat bundle has loaded. */
+    ready: boolean;
+    open: boolean;
+    unread: number;
+}
+/** Each event and what its callback receives. */
+export interface DinghyEvents {
+    ready: undefined;
+    open: undefined;
+    close: undefined;
+    unread: number;
+    /** The visitor's message reached the server. `body` is null for an image. */
+    "message:sent": {
+        body: string | null;
+    };
+    /** A reply arrived while the page was open. `body` is null for an image. */
+    "message:received": {
+        body: string | null;
+    };
+    "conversation:started": undefined;
+}
+export type DinghyEvent = keyof DinghyEvents;
+/** The public API on the host page, `window.Dinghy`. */
+export interface DinghyApi {
+    open(options?: OpenOptions): void;
+    close(): void;
+    toggle(): void;
+    /** Shows or hides the launcher button. */
+    show(): void;
+    hide(): void;
+    identify(identity: Identity): void;
+    reset(): void;
+    setContext(data: PageContext): void;
+    configure(options: Appearance): void;
+    /** Calls `callback` on each event, and returns a function that removes it. */
+    on<E extends DinghyEvent>(event: E, callback: (data: DinghyEvents[E]) => void): () => void;
+    readonly state: DinghyState;
+}
+/** A call queued before the loader runs, as `Dinghy = { q: [["open"]] }`. */
+export type QueuedCall = [string, ...unknown[]];
+/** What the chat bundle gives the loader once it runs. */
+export interface ChatHandlers {
+    open(message: string | undefined): void;
+    close(): void;
+    /** identify() or reset(): start again. */
+    session(): void;
+    /** setContext() was called. */
+    context(): void;
+}
+/** Each event's callbacks. The loader keeps them, and the chat bundle calls them. */
+export type Listeners = {
+    [E in DinghyEvent]?: Set<(data: DinghyEvents[E]) => void>;
+};
+/** What the loader hands to the chat bundle. */
+export interface WidgetContext {
+    publicKey: string;
+    base: string;
+    shadow: ShadowRoot;
+    /** False when the page set data-mascot="false". Every state still has its text. */
+    mascot: boolean;
+    /** The full-page chat that a reply email opens, on the Dinghy server's own origin. */
+    page?: boolean;
+    /** Set by identify() and cleared by reset(). */
+    identity: Identity | null;
+    /** The last setContext() value, as the page gave it. */
+    pageContext: unknown;
+    /** The chat bundle sets this when it runs, then opens the chat if `wanted` asks for it. */
+    chat?: ChatHandlers;
+    /** An open() made before the chat bundle ran, with its message. */
+    wanted?: [string | undefined] | undefined;
+    /** The loader's `Dinghy.state`, which the chat bundle keeps up to date. */
+    state: DinghyState;
+    listeners: Listeners;
+}
+export declare const RESET_PREFIX = "dinghy:reset:";
+/** Storage can throw in a private window or with blocked site data. */
+export declare function readToken(publicKey: string): string | null;
+export declare function writeToken(publicKey: string, token: string | null): void;
+/** Whether the chat was open in this tab before a reload. Only a visitor with a token has this. */
+export declare function wasOpen(publicKey: string): boolean;
+export declare function rememberOpen(publicKey: string, open: boolean): void;
+/**
+ * Tells other tabs of this site to start again. A storage event fires only in other tabs. The key
+ * goes at once, so nothing stays stored for a visitor who never chatted.
+ */
+export declare function broadcastReset(publicKey: string): void;

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@dinghy-chat/widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.12.0",
+  "description": "Add the Dinghy chat to your site from code, with a typed API.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://dinghy.chat/docs/add-to-your-site",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dinghy-chat/dinghy.git",
+    "directory": "packages/widget"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "esbuild src/index.ts --bundle --format=esm --target=es2022 --outfile=dist/index.js && tsc -p tsconfig.npm.json"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "preact": "^11.2.0"
+  }
+}