{"_id":"@1interface/embed","_rev":"20-6f9f8fa002e6feff5f8851536eb744ec","name":"@1interface/embed","dist-tags":{"moet":"0.7.0-moet.1","latest":"0.10.0"},"versions":{"0.1.0":{"name":"@1interface/embed","version":"0.1.0","license":"UNLICENSED","_id":"@1interface/embed@0.1.0","maintainers":[{"name":"rahulgopathi","email":"rahul@aiatcore.com"},{"name":"brendenaac","email":"brenden@aiatcore.com"},{"name":"tarikaac","email":"tarik@aiatcore.com"},{"name":"itsrehman14","email":"mohammed@aiatcore.com"}],"homepage":"https://github.com/aiatcore/1interface-chat#readme","bugs":{"url":"https://github.com/aiatcore/1interface-chat/issues"},"dist":{"shasum":"df08ff4fcfe0a5f7fbc0068006cf5b244659be2d","tarball":"https://registry.npmjs.org/@1interface/embed/-/embed-0.1.0.tgz","fileCount":10,"integrity":"sha512-KVHpCcwyBqjbEuV232mIjH5BwGdytJhxcyJyuE3tmvQC9G+ZMF6K3JYTKem63f2JbrjsLAHcNmE2EPRwWi2Jjw==","signatures":[{"sig":"MEQCIAvpG75Pk2sA0E+M2ux2n/IG6EdfgTL3TSjyLK1gctDOAiBBY4iOSQ5wPOVmWwKgDEg1m9ApP+lABkhLQPoDs8xBig==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":54215},"main":"./dist/embed.js","type":"module","_from":"file:1interface-embed-0.1.0.tgz","types":"./dist/lib.d.ts","module":"./dist/embed.esm.js","exports":{".":{"types":"./dist/lib.d.ts","import":"./dist/embed.esm.js","default":"./dist/embed.js"},"./embed.js":"./dist/embed.js","./embed.min.js":"./dist/embed.min.js"},"private":false,"scripts":{"dev":"node scripts/build.mjs","test":"vitest","build":"node scripts/build.mjs && tsc --emitDeclarationOnly","typecheck":"tsc --noEmit"},"_npmUser":{"name":"tarikaac","email":"tarik@aiatcore.com"},"_resolved":"/private/var/folders/6y/4796nmdd65jdvh0xnf31j_j80000gn/T/15b53429909b5430a93101169a457574/1interface-embed-0.1.0.tgz","_integrity":"sha512-KVHpCcwyBqjbEuV232mIjH5BwGdytJhxcyJyuE3tmvQC9G+ZMF6K3JYTKem63f2JbrjsLAHcNmE2EPRwWi2Jjw==","repository":{"url":"git+https://github.com/aiatcore/1interface-chat.git","type":"git","directory":"packages/embed"},"_npmVersion":"11.6.2","description":"The `\n\n```\n\n`appUrl` is the full, ready-to-frame chat URL 1Interface hands you (`{origin}/{orgId}/chat`). The\nloader frames it verbatim and never assembles a path.\n\n### Attribute-only variant\n\nFor a CMS that strips inline `\n```\n\n## Configuration\n\nAll options are optional except `appUrl`. Pass them in the `init` call (or as `data-*` attributes).\n\n### Connection & content\n\n| Option | Attribute | Type | Default | Notes |\n|---|---|---|---|---|\n| `appUrl` | `data-app-url` | string | — | **Required.** Full chat URL, framed verbatim. |\n| `defaultAppearanceMode` | `data-default-appearance-mode` | `\"light\"`\\|`\"dark\"`\\|`\"system\"` | `\"system\"` | Passed to the app on init. |\n| `layout` | `data-layout` | `\"classic\"`\\|`\"workspace\"` | `\"classic\"` | Chat layout for this placement; `workspace` renders a service rail beside the thread. |\n| `services` | — | `{ key, label, category?, prompt }[]` | `[]` | Workspace-rail entries; clicking one sends its `prompt`. Structured, so JS-only. |\n| `host` | `data-host` | string | — | Optional identifier the embedder announces in the `parent:init` payload (e.g. `\"control-panel\"`); the chat may tailor UI to a recognized host. |\n| `auth` | — | `{ getToken(): Promise<{ accessToken, expiresAt? }> }` | `null` | **Inherit auth only.** When the org's auth mode is `inherit`, the loader calls `getToken()` on every `chat:tokenRequest` and hands the token to the frame. `expiresAt` is epoch ms or an ISO 8601 string. Structured, so JS-only. Pair with `on(\"auth:error\", …)` + `retryAuth()` to recover a lapsed session (see [Recovering a lapsed session](#recovering-a-lapsed-session)). |\n\n### Launcher & layout\n\n| Option | Attribute | Type | Default | Notes |\n|---|---|---|---|---|\n| `label` | `data-label` | string | `\"Chat with us\"` | The widget's accessible name — launcher tooltip, panel `aria-label`, iframe `title`. Applies in every mode. |\n| `showLauncher` | `data-show-launcher=\"false\"` | boolean | `true` | `false` hides the floating bubble for a **custom trigger** — the corner popup still opens from your own `open()` call. Ignored when `container` is set (controlled mode never has a launcher). To dock the chat inline instead, use `container`. |\n| `container` | — | `HTMLElement` | `null` | Controlled mode: dock the chat into this element — **no launcher regardless of `showLauncher`**, always open. ESM/ bundled apps only. |\n| `launcher.color` | `data-launcher-color` | string | `\"#3B4FFE\"` | The bubble's ground — set it to the orb's tone so the orb cuts in seamlessly while loading. Also backs the icon bubble. |\n| `launcher.icon` | `data-launcher-icon` | string \\| `null` | `null` | **Primary visual — replaces the orb when set.** An image URL, a `data:` URI, or an emoji/short text. `null` shows the animated orb. A bad image URL falls back to the built-in bubble. See [Static icon launcher](#static-icon-launcher). |\n| `launcher.size` | `data-launcher-size` | number | `64` | Button diameter in px; the inner icon derives from it (~0.5). |\n| `position` | `data-position` | `\"start\"`\\|`\"end\"` | `\"end\"` | Which corner, by logical edge. Mirrors with the host page's `dir` — `end` is right in LTR, left in RTL. |\n| `offset` | `data-offset-bottom` (bottom only) | `{ side?, bottom? }` | `{ 24, 24 }` | Pixels from the edge. Raise `bottom` to clear an existing floating button. |\n| `zIndex` | — | number | `2147483000` | Stacking above the host page. |\n| `panel` | — | `{ width?, height? }` | `{ 360, 640 }` | Popup size in px. |\n| `expandable` | `data-expandable` | boolean | `true` | Show the in-chat Expand button that widens the desktop panel to a reading size. `false` hides it. No effect on mobile (a full sheet) or controlled mode. |\n| `openOnLoad` | `data-open-on-load` | boolean | `false` | Open the panel immediately. |\n| `preload` | — | `\"eager\"`\\|`\"idle\"`\\|`\"open\"` | `\"idle\"` | When to mount the iframe. |\n\n**Attribute-only limits:** `container`, `offset.side`, `zIndex`, `panel`, `preload`, and event\nhandlers are JS-only.\n\n### Static icon launcher\n\nSet `launcher.icon` to show a static icon **in place of** the animated orb — rendered immediately, no\nvideo, no loading shimmer.\n\n```js\nOneInterfaceChat.init({\n appUrl: \"https://chat.1interface.com/acme/chat\",\n launcher: { icon: \"https://acme.com/logo.svg\", size: 72 },\n});\n```\n\n- **Accepts** an absolute image URL, a protocol-/root-relative URL, a `data:` URI, or an emoji/short\n text (`\"🤖\"`). A bare word is treated as text, not an image — image icons must be absolute,\n root-relative, or a `data:` URI (there is no origin to resolve a relative path on the host page).\n- **Fallback.** If an image URL fails to load, the launcher falls back to the built-in chat bubble.\n- **`color`** still sets the ground behind the icon; a transparent logo shows it around the edges\n (the icon uses `object-fit: contain`, never cropped).\n\n## JavaScript API\n\nThe script installs `window.OneInterfaceChat`. Because the tag is `async`, queue calls before load\nvia `window.OneInterfaceChatQueue`; the same calls work directly after load.\n\n```js\nwindow.OneInterfaceChatQueue = [\n [\"init\", { appUrl: \"https://chat.1interface.com/acme/chat\" }],\n [\"on\", \"chat:unread\", (p) => updateBadge(p.count)],\n];\n// after load:\nOneInterfaceChat.open();\n```\n\n### Global object\n\n| Member | Returns | Description |\n|---|---|---|\n| `init(options)` | instance | Creates the widget. Calling again destroys the previous one and recreates it. |\n| `instance()` | instance \\| `null` | The current live instance. |\n| `protocolVersion` | number | postMessage protocol version. |\n\n### Instance methods\n\n| Method | Returns | Effect |\n|---|---|---|\n| `open()` | void | Mounts the frame if needed, opens the panel, emits `open`. |\n| `close()` | void | Closes the panel, emits `close`. |\n| `toggle()` | void | Flips open/closed. |\n| `isOpen()` | boolean | Current panel state. |\n| `logout()` | void | Tells the frame to end the session. |\n| `retryAuth()` | void | `inherit` auth: after a silent re-auth, tells the frame to re-ask for a token and recover (no reload / \"Try again\"). No-op without `auth`. |\n| `on(type, handler)` | unsubscribe fn | Subscribe to an event; returns a remover. |\n| `destroy()` | void | Removes the DOM, listeners, and timers. |\n| `config()` | options | Snapshot of the resolved options in effect. |\n\n### Events\n\nSubscribe with `on(type, handler)`. `on(\"*\", …)` receives every event as `{ type, payload }`.\n\n**Loader lifecycle events:**\n\n| Event | Fires when |\n|---|---|\n| `open` / `close` | Panel opened / closed. |\n| `ready` | The chat acknowledged init (`chat:initAck`). Payload comes from the app. |\n| `error` | A loader failure — `{ code, message, cause }`. Codes: `missing-app-url`, `init-timeout`, `listener-failed`, `auth-not-configured`. |\n| `auth:error` | **Inherit auth only.** The frame reported the session is dead — `{ reason }` (`no_token` \\| `token_expired` \\| `token_rejected`). Re-authenticate the user, then call `retryAuth()` to recover (see [Recovering a lapsed session](#recovering-a-lapsed-session)), or clear your session. |\n\n`error` events are **buffered**: failures during construction are replayed to the first\n`on(\"error\")` subscriber, so late subscription still catches them (the buffer drains once).\n\n**Frame messages**, re-emitted verbatim by their own name (subscribe with the full `chat:` type):\n`chat:ready`, `chat:initAck`, `chat:close`, `chat:unread` (`{ count }`),\n`chat:conversationChange`, `chat:messagesChange`, `chat:logoutRequested`, `chat:branding`\n(`{ orbVideoUrl, orbBackground }`), `chat:authError` (`{ reason }`, also surfaced as `auth:error`).\n\n**Inherit auth wire messages:** under `inherit` auth mode the frame sends `chat:tokenRequest`\n(`{ requestId }`) and the loader replies `parent:token` (`{ requestId, accessToken, expiresAt }` or\n`{ requestId, error }`); `retryAuth()` posts `parent:retryAuth` (signal only). These are brokered by\nthe loader — you supply the `auth` option, listen for `auth:error`, and call `retryAuth()`; you never\nhandle the wire messages directly.\n\n### Recovering a lapsed session\n\nThe token you supply eventually stops working (it expires, or the session is revoked). The chat then\nstops asking and fires `auth:error`. **Only you can fix it** — the chat can't re-establish the login,\nonly re-ask you for a token — so recovery is a two-step handshake in your `auth:error` handler:\n\n```js\n[\"on\", \"auth:error\", async () => {\n await myApp.reauthenticate(); // 1. fix your session — silent refresh, hidden SSO, or redirect\n OneInterfaceChat.retryAuth(); // 2. tell the chat to re-ask getToken and resume where it left off\n}]\n```\n\nWithout step 2 the visitor is stranded on a \"session ended\" screen with a **Try again** button they\nmust press. `retryAuth()` makes recovery seamless — and it is the **only** way to auto-recover a\n**silent, in-page** re-auth (a full-page redirect reloads the frame and recovers on its own, so\n`retryAuth()` is then optional but harmless). It carries **no token** — the chat pulls the new one\nthrough `auth.getToken`, which must return the fresh token once you've re-authenticated. Safe to call\nany time; a no-op if `auth` is unset.\n\n## Bundled apps (ESM + controlled mode)\n\nAn app with a bundler (React/Angular, e.g. Control Panel) imports the loader instead of the script\ntag — no global, no queue:\n\n```js\nimport { createInstance } from \"@1interface/embed\";\n\nconst chat = createInstance({\n appUrl: \"https://chat.1interface.com/acme/chat\",\n container: myElement, // controlled mode: dock the chat into your element (no launcher)\n});\n```\n\n**Controlled mode** (`container` set) renders the chat *inside* the element you pass, filling it,\nalways open — no launcher chrome, and `close()` / `toggle()`-to-closed are no-ops (the host owns the\nbox). Its `pointer-events` inherits from the container, so a host drag/resize that sets\n`pointer-events: none` reaches the iframe. In the default launcher mode, `open`/`close` drive the\nfloating panel as usual.\n\n## Requirements & caveats\n\n- **The widget mirrors with the host page's direction.** A `dir=\"rtl\"` page places the launcher and\n panel on the left automatically — `position` is logical (`start`/`end`), so no per-language config.\n Only the loader chrome mirrors; the chat *content* follows RTL when the chat app itself supports it.\n- **The chat app must allow being framed.** It must not send `X-Frame-Options: SAMEORIGIN`, and its\n CSP `frame-ancestors` must list the client's origin. A locked-down deployment blocks the embed —\n this is fixed at the deployment, not in the loader.\n- **The chat host must implement the frame half.** `defaultAppearanceMode` and the `chat:*`\n events only take effect against a chat deployment that runs the frame side of the protocol\n (`src/app/iframe/parentMessenger.ts` in the web client). The launcher, layout, and local\n `open`/`close`/`error` work regardless.\n- **Renaming an option breaks every client who pasted the old snippet.** Keep this README,\n `snippet.html`, and `src/types.ts` in step.\n\n## Build\n\n```bash\npnpm --filter @1interface/embed run build # esbuild → dist/embed.js + embed.min.js (IIFE) + embed.esm.js (ESM), tsc → .d.ts\npnpm --filter @1interface/embed test\n```\n","readmeFilename":"README.md"}