@callembed/vue 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sealby
+
+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,80 @@
-# Temporary Holding Version
+# `@callembed/vue`
 
-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.
+Vue 3 components and composables for [CallEmbed](https://callembed.sealby.me) — a **thin wrapper** over [`@callembed/sdk`](../sdk).
+
+**Product model:** customer-service queue only. An end user on a web page clicks “talk to a human” → rings a project queue → an agent answers. This package does **not** implement person-to-person calling.
+
+Call / auth / LiveKit connection logic stays in `@callembed/sdk`. Remote audio is already handled by the headless SDK (`hidePanel: true`).
+
+## Install
+
+```bash
+npm install @callembed/vue @callembed/sdk livekit-client vue
+```
+
+Peer dependencies: `vue` (^3.4), `@callembed/sdk`, and `livekit-client` (optional peer; required transitively by the SDK).
+
+## Quick start
+
+```vue
+<script setup lang="ts">
+import { CallEmbedProvider, CallEmbedButton } from "@callembed/vue";
+import "@callembed/vue/styles.css";
+</script>
+
+<template>
+  <CallEmbedProvider
+    publishable-key="pk_…"
+    api-base-url=""
+    locale="en"
+    queue="onboarding"
+  >
+    <CallEmbedButton />
+  </CallEmbedProvider>
+</template>
+```
+
+### Plugin
+
+```ts
+import { createApp } from "vue";
+import { CallEmbedPlugin } from "@callembed/vue";
+
+createApp(App).use(CallEmbedPlugin).mount("#app");
+```
+
+### Composable
+
+```ts
+import { useCallEmbed } from "@callembed/vue";
+
+const { uiState, muted, start, end, setMuted } = useCallEmbed();
+// uiState: idle | ringing | connected | ended | error
+```
+
+## API
+
+| Export | Role |
+|--------|------|
+| `CallEmbedProvider` | Calls `CallEmbed.init` on the client; provides context |
+| `CallEmbedButton` | Start / end button + optional mute + status line (en / zh-TW) |
+| `useCallEmbed()` | `{ status, uiState, callId, muted, error, start, end, setMuted, … }` |
+| `CallEmbedPlugin` | Registers Provider + Button globally |
+
+`uiState` maps SDK `answered` → `connected`, and folds `connecting` into `ringing`. Locale strings match `@callembed/sdk/ui` (`en` + `zh-TW`). Theme: `--ce-*` CSS variables.
+
+Unmount or `publishableKey` / `apiBaseUrl` change hangs up any active/ringing call. Init/start failures set `error` uiState.
+
+## SSR / Nuxt
+
+- No `window` / `document` access at import time.
+- `CallEmbed.init` runs only when `typeof window !== "undefined"` (client).
+- Use inside a client-only boundary (`<ClientOnly>` in Nuxt) if the button must not SSR-render interactive call UI.
+
+## Builds
+
+Emits ESM (`dist/index.js`), CJS (`dist/index.cjs`), and TypeScript declarations (`dist/index.d.ts`), plus `dist/styles.css`.
+
+## Publishing
+
+Published via the multi-package tag workflow (see [`docs/RELEASING.md`](../../docs/RELEASING.md)). Local allowlist check: `npm run pack:verify -w @callembed/vue`.

package/dist/index.cjs

@@ -0,0 +1,467 @@
+'use strict';
+
+var sdk = require('@callembed/sdk');
+var vue = require('vue');
+var ui = require('@callembed/sdk/ui');
+
+// src/provider.ts
+
+// src/types.ts
+function toUiState(status) {
+  switch (status) {
+    case "connecting":
+    case "ringing":
+      return "ringing";
+    case "answered":
+      return "connected";
+    case "ended":
+      return "ended";
+    case "error":
+      return "error";
+    case "idle":
+    default:
+      return "idle";
+  }
+}
+var CALL_EMBED_KEY = /* @__PURE__ */ Symbol("callembed");
+
+// src/provider.ts
+function toErrorState(err) {
+  if (err instanceof sdk.CallEmbedError) {
+    return { code: err.code, message: err.message };
+  }
+  return {
+    code: "call_failed",
+    message: err instanceof Error ? err.message : String(err)
+  };
+}
+function isActiveStatus(status) {
+  return status === "connecting" || status === "ringing" || status === "answered";
+}
+function bindCall(call, handlers) {
+  const offs = [
+    call.on("statusChange", ({ status }) => {
+      handlers.setStatus(status);
+      if (call.callId && call.callId !== "pending") {
+        handlers.setCallId(call.callId);
+      }
+    }),
+    call.on("muteChange", ({ muted }) => {
+      handlers.setMuted(muted);
+    }),
+    call.on("error", ({ code, message, callId }) => {
+      handlers.setError({ code, message });
+      handlers.setStatus("error");
+      if (callId && callId !== "pending") handlers.setCallId(callId);
+    }),
+    call.on("ended", ({ callId }) => {
+      handlers.setStatus("ended");
+      if (callId && callId !== "pending") handlers.setCallId(callId);
+    })
+  ];
+  return () => {
+    offs.forEach((off) => off());
+  };
+}
+var CallEmbedProvider = vue.defineComponent({
+  name: "CallEmbedProvider",
+  props: {
+    publishableKey: { type: String, required: true },
+    apiBaseUrl: { type: String, required: true },
+    locale: { type: String, default: void 0 },
+    copy: {
+      type: Object,
+      default: void 0
+    },
+    branding: { type: Boolean, default: void 0 },
+    debug: { type: Boolean, default: void 0 },
+    queue: { type: String, default: void 0 }
+  },
+  slots: Object,
+  setup(props, { slots }) {
+    const status = vue.ref("idle");
+    const callId = vue.ref(null);
+    const muted = vue.ref(false);
+    const error = vue.ref(null);
+    const resolvedLocale = vue.ref(props.locale ?? "en");
+    const callRef = vue.ref(null);
+    let unbind = null;
+    const copyKey = vue.computed(() => JSON.stringify(props.copy ?? {}));
+    const brandingValue = vue.computed(() => props.branding !== false);
+    function hangUpActive() {
+      unbind?.();
+      unbind = null;
+      const call = callRef.value ?? sdk.CallEmbed.getActiveCall();
+      callRef.value = null;
+      if (call && isActiveStatus(call.status)) {
+        void call.hangUp();
+      }
+    }
+    function runInit() {
+      if (typeof window === "undefined") return;
+      try {
+        sdk.CallEmbed.init({
+          publishableKey: props.publishableKey,
+          apiBaseUrl: props.apiBaseUrl,
+          locale: props.locale,
+          copy: props.copy,
+          branding: props.branding,
+          debug: props.debug
+        });
+        const runtime = sdk.CallEmbed._getRuntime();
+        if (runtime) resolvedLocale.value = runtime.locale;
+      } catch (err) {
+        const state = toErrorState(err);
+        error.value = state;
+        status.value = "error";
+      }
+    }
+    vue.watch(
+      () => [
+        props.publishableKey,
+        props.apiBaseUrl,
+        props.locale,
+        copyKey.value,
+        brandingValue.value,
+        props.debug
+      ],
+      () => {
+        runInit();
+      },
+      { immediate: true }
+    );
+    vue.watch(
+      () => [props.publishableKey, props.apiBaseUrl],
+      (_next, _prev, onCleanup) => {
+        onCleanup(() => {
+          hangUpActive();
+        });
+      },
+      { immediate: true }
+    );
+    async function start(options = {}) {
+      try {
+        const q = options.queue ?? props.queue;
+        if (!q?.trim()) {
+          throw new sdk.CallEmbedError(
+            "invalid_queue",
+            "queue is required (pass queue on the provider, button, or start())."
+          );
+        }
+        error.value = null;
+        muted.value = false;
+        const userOn = options.on;
+        const call = await sdk.CallEmbed.startCall({
+          ...options,
+          queue: q,
+          hidePanel: true,
+          on: {
+            ...userOn,
+            statusChange: (payload) => {
+              status.value = payload.status;
+              userOn?.statusChange?.(payload);
+            },
+            muteChange: (payload) => {
+              muted.value = payload.muted;
+              userOn?.muteChange?.(payload);
+            },
+            error: (payload) => {
+              error.value = { code: payload.code, message: payload.message };
+              status.value = "error";
+              if (payload.callId && payload.callId !== "pending") {
+                callId.value = payload.callId;
+              }
+              userOn?.error?.(payload);
+            },
+            ended: (payload) => {
+              status.value = "ended";
+              if (payload.callId && payload.callId !== "pending") {
+                callId.value = payload.callId;
+              }
+              userOn?.ended?.(payload);
+            },
+            ringing: (payload) => {
+              callId.value = payload.callId;
+              userOn?.ringing?.(payload);
+            },
+            answered: (payload) => {
+              callId.value = payload.callId;
+              userOn?.answered?.(payload);
+            }
+          }
+        });
+        unbind?.();
+        callRef.value = call;
+        status.value = call.status;
+        if (call.callId !== "pending") callId.value = call.callId;
+        unbind = bindCall(call, {
+          setStatus: (s) => {
+            status.value = s;
+          },
+          setCallId: (id) => {
+            callId.value = id;
+          },
+          setMuted: (m) => {
+            muted.value = m;
+          },
+          setError: (e) => {
+            error.value = e;
+          }
+        });
+        return call;
+      } catch (err) {
+        const state = toErrorState(err);
+        error.value = state;
+        status.value = "error";
+        if (err instanceof sdk.CallEmbedError) throw err;
+        throw new sdk.CallEmbedError("call_failed", state.message);
+      }
+    }
+    async function end() {
+      const call = callRef.value ?? sdk.CallEmbed.getActiveCall();
+      if (!call) {
+        status.value = "idle";
+        return;
+      }
+      await call.hangUp();
+    }
+    async function setMuted(next) {
+      const call = callRef.value ?? sdk.CallEmbed.getActiveCall();
+      if (!call) {
+        muted.value = next;
+        return;
+      }
+      await call.setMuted(next);
+    }
+    const api = vue.reactive({
+      get status() {
+        return status.value;
+      },
+      get uiState() {
+        return toUiState(status.value);
+      },
+      get callId() {
+        return callId.value;
+      },
+      get muted() {
+        return muted.value;
+      },
+      get error() {
+        return error.value;
+      },
+      get locale() {
+        return resolvedLocale.value;
+      },
+      start,
+      end,
+      setMuted,
+      get defaultQueue() {
+        return props.queue;
+      }
+    });
+    vue.provide(CALL_EMBED_KEY, api);
+    return () => slots.default?.();
+  }
+});
+function useCallEmbed() {
+  const ctx = vue.inject(CALL_EMBED_KEY, null);
+  if (!ctx) {
+    throw new Error("useCallEmbed() must be used within <CallEmbedProvider>.");
+  }
+  return ctx;
+}
+function statusLabel(copy, uiState, sdkStatus) {
+  switch (uiState) {
+    case "idle":
+      return copy.ready;
+    case "ringing":
+      return sdkStatus === "connecting" ? copy.connecting : copy.ringing;
+    case "connected":
+      return copy.answered;
+    case "ended":
+      return copy.ended;
+    case "error":
+      return copy.error;
+    default:
+      return copy.ready;
+  }
+}
+function runtimeForCopy(locale, copyOverrides = {}) {
+  return {
+    publishableKey: "",
+    apiBaseUrl: "",
+    locale,
+    copyOverrides,
+    branding: true,
+    debug: false
+  };
+}
+
+// src/CallEmbedButton.ts
+var CallEmbedButton = vue.defineComponent({
+  name: "CallEmbedButton",
+  props: {
+    /** Queue to ring. Falls back to `CallEmbedProvider` `queue`. */
+    queue: { type: String, default: void 0 },
+    /** Idle-state label; defaults to locale `launchDefault`. */
+    label: { type: String, default: void 0 },
+    /** Optional metadata forwarded to `startCall`. */
+    metadata: {
+      type: Object,
+      default: void 0
+    },
+    /** Optional caller display name. */
+    displayName: { type: String, default: void 0 },
+    /** Show a status line under the button. Default: `true`. */
+    showStatus: { type: Boolean, default: true },
+    /** Show mute control while ringing/connected. Default: `true`. */
+    showMute: { type: Boolean, default: true },
+    disabled: { type: Boolean, default: false }
+  },
+  emits: {
+    error: (_error) => true
+  },
+  setup(props, { emit, attrs }) {
+    const embed = useCallEmbed();
+    const busy = vue.ref(false);
+    const copy = vue.computed(() => ui.resolveCopy(runtimeForCopy(embed.locale)));
+    const inCall = vue.computed(
+      () => embed.uiState === "ringing" || embed.uiState === "connected"
+    );
+    const buttonLabel = vue.computed(
+      () => inCall.value ? copy.value.hangup : props.label ?? copy.value.launchDefault
+    );
+    const statusText = vue.computed(() => {
+      if (embed.uiState === "error" && embed.error) {
+        return ui.friendlyErrorMessage(
+          copy.value,
+          embed.error.code,
+          embed.error.message
+        );
+      }
+      return statusLabel(copy.value, embed.uiState, embed.status);
+    });
+    const tone = vue.computed(
+      () => embed.uiState === "error" ? "error" : embed.uiState === "connected" ? "ok" : void 0
+    );
+    async function onClick() {
+      if (busy.value) return;
+      busy.value = true;
+      try {
+        if (inCall.value) {
+          await embed.end();
+        } else {
+          await embed.start({
+            queue: props.queue ?? embed.defaultQueue,
+            metadata: props.metadata,
+            displayName: props.displayName
+          });
+        }
+      } catch (err) {
+        const ce = err instanceof sdk.CallEmbedError ? err : new sdk.CallEmbedError(
+          "call_failed",
+          err instanceof Error ? err.message : String(err)
+        );
+        emit("error", ce);
+      } finally {
+        busy.value = false;
+      }
+    }
+    async function onMuteClick() {
+      if (busy.value) return;
+      busy.value = true;
+      try {
+        await embed.setMuted(!embed.muted);
+      } catch (err) {
+        const ce = err instanceof sdk.CallEmbedError ? err : new sdk.CallEmbedError(
+          "call_failed",
+          err instanceof Error ? err.message : String(err)
+        );
+        emit("error", ce);
+      } finally {
+        busy.value = false;
+      }
+    }
+    return () => {
+      const rootClass = ["ce-vue-root", attrs.class].filter(Boolean).join(" ");
+      const children = [
+        vue.h(
+          "button",
+          {
+            type: "button",
+            class: "ce-vue-button",
+            "data-state": embed.uiState,
+            disabled: props.disabled || busy.value,
+            "aria-busy": busy.value || void 0,
+            onClick: () => {
+              void onClick();
+            }
+          },
+          buttonLabel.value
+        )
+      ];
+      if (props.showMute && inCall.value) {
+        children.push(
+          vue.h(
+            "button",
+            {
+              type: "button",
+              class: "ce-vue-mute",
+              disabled: busy.value,
+              onClick: () => {
+                void onMuteClick();
+              }
+            },
+            embed.muted ? copy.value.unmute : copy.value.mute
+          )
+        );
+      }
+      if (props.showStatus) {
+        children.push(
+          vue.h(
+            "p",
+            {
+              class: "ce-vue-status",
+              "data-tone": tone.value,
+              "data-state": embed.uiState
+            },
+            statusText.value
+          )
+        );
+      }
+      return vue.h("div", { class: rootClass, "data-ce-vue": "" }, children);
+    };
+  }
+});
+
+// src/plugin.ts
+var CallEmbedPlugin = {
+  install(app, options = {}) {
+    app.component(options.providerName ?? "CallEmbedProvider", CallEmbedProvider);
+    app.component(options.buttonName ?? "CallEmbedButton", CallEmbedButton);
+  }
+};
+
+Object.defineProperty(exports, "enCopy", {
+  enumerable: true,
+  get: function () { return ui.enCopy; }
+});
+Object.defineProperty(exports, "friendlyErrorMessage", {
+  enumerable: true,
+  get: function () { return ui.friendlyErrorMessage; }
+});
+Object.defineProperty(exports, "resolveCopy", {
+  enumerable: true,
+  get: function () { return ui.resolveCopy; }
+});
+Object.defineProperty(exports, "zhTwCopy", {
+  enumerable: true,
+  get: function () { return ui.zhTwCopy; }
+});
+exports.CALL_EMBED_KEY = CALL_EMBED_KEY;
+exports.CallEmbedButton = CallEmbedButton;
+exports.CallEmbedPlugin = CallEmbedPlugin;
+exports.CallEmbedProvider = CallEmbedProvider;
+exports.statusLabel = statusLabel;
+exports.toUiState = toUiState;
+exports.useCallEmbed = useCallEmbed;