@callembed/react 0.0.0-stage → 0.1.0

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,93 @@
-# Temporary Holding Version
+# `@callembed/react`
 
-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.
+React components and hooks 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`), so this package does not pull in `@livekit/components-react` by default.
+
+## Install
+
+```bash
+npm install @callembed/react @callembed/sdk livekit-client react react-dom
+```
+
+Peer dependencies: `react`, `react-dom`, `@callembed/sdk`, and `livekit-client` (optional peer; required transitively by the SDK).
+
+## Quick start
+
+```tsx
+"use client"; // Next.js App Router
+
+import { CallEmbedProvider, CallEmbedButton } from "@callembed/react";
+import "@callembed/react/styles.css";
+
+export function SupportCall() {
+  return (
+    <CallEmbedProvider
+      publishableKey="pk_…"
+      apiBaseUrl=""
+      locale="en"
+      queue="onboarding"
+    >
+      <CallEmbedButton />
+    </CallEmbedProvider>
+  );
+}
+```
+
+### Hook
+
+```tsx
+import { useCallEmbed } from "@callembed/react";
+
+function Controls() {
+  const { uiState, status, muted, start, end, setMuted } = useCallEmbed();
+  // uiState: idle | ringing | connected | ended | error
+  // status:  idle | connecting | ringing | answered | ended | error  (SDK)
+  return (
+    <>
+      <button type="button" onClick={() => void start({ queue: "support" })}>
+        Talk
+      </button>
+      <button type="button" onClick={() => void end()}>
+        Hang up
+      </button>
+      <button type="button" onClick={() => void setMuted(!muted)}>
+        {muted ? "Unmute" : "Mute"}
+      </button>
+      <span>{uiState}</span>
+    </>
+  );
+}
+```
+
+## API
+
+| Export | Role |
+|--------|------|
+| `CallEmbedProvider` | Calls `CallEmbed.init` in `useEffect` (SSR-safe); provides context |
+| `CallEmbedButton` | Start / end button + optional mute + status line (en / zh-TW) |
+| `useCallEmbed()` | `{ status, uiState, callId, muted, error, start, end, setMuted, … }` |
+
+`uiState` maps SDK `answered` → `connected`, and folds `connecting` into `ringing` for button UX. Locale strings match `@callembed/sdk/ui` (`en` + `zh-TW`).
+
+Theme: same `--ce-*` CSS variables as the vanilla SDK UI.
+
+## SSR / Next.js
+
+- Entry is marked `"use client"`.
+- No `window` / `document` access at import time; init runs in `useEffect`.
+- Import as a Client Component from Server Components.
+
+## Builds
+
+Emits ESM (`dist/index.js`), CJS (`dist/index.cjs`), and TypeScript declarations (`dist/index.d.ts`), plus `dist/styles.css`.
+
+## Minimal example
+
+See [`examples/react-vite`](../../examples/react-vite) in this repo.
+
+## Publishing
+
+Published via the multi-package tag workflow (see [`docs/RELEASING.md`](../../docs/RELEASING.md)). Local allowlist check: `npm run pack:verify -w @callembed/react`.

package/dist/index.cjs

@@ -0,0 +1,371 @@
+'use strict';
+"use client";
+
+var sdk = require('@callembed/sdk');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+var ui = require('@callembed/sdk/ui');
+
+// src/context.tsx
+
+// 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 CallEmbedReactContext = react.createContext(null);
+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());
+  };
+}
+function CallEmbedProvider({
+  children,
+  publishableKey,
+  apiBaseUrl,
+  locale,
+  copy,
+  branding,
+  debug,
+  queue
+}) {
+  const [status, setStatus] = react.useState("idle");
+  const [callId, setCallId] = react.useState(null);
+  const [muted, setMutedState] = react.useState(false);
+  const [error, setError] = react.useState(null);
+  const [resolvedLocale, setResolvedLocale] = react.useState(locale ?? "en");
+  const callRef = react.useRef(null);
+  const unbindRef = react.useRef(null);
+  const copyKey = JSON.stringify(copy ?? {});
+  const hangUpActive = react.useCallback(() => {
+    unbindRef.current?.();
+    unbindRef.current = null;
+    const call = callRef.current ?? sdk.CallEmbed.getActiveCall();
+    callRef.current = null;
+    if (call && isActiveStatus(call.status)) {
+      void call.hangUp();
+    }
+  }, []);
+  react.useEffect(() => {
+    try {
+      sdk.CallEmbed.init({
+        publishableKey,
+        apiBaseUrl,
+        locale,
+        copy,
+        branding,
+        debug
+      });
+      const runtime = sdk.CallEmbed._getRuntime();
+      if (runtime) setResolvedLocale(runtime.locale);
+    } catch (err) {
+      const state = toErrorState(err);
+      setError(state);
+      setStatus("error");
+    }
+  }, [publishableKey, apiBaseUrl, locale, copyKey, branding, debug]);
+  react.useEffect(() => {
+    return () => {
+      hangUpActive();
+    };
+  }, [publishableKey, apiBaseUrl, hangUpActive]);
+  const start = react.useCallback(
+    async (options = {}) => {
+      try {
+        const q = options.queue ?? queue;
+        if (!q?.trim()) {
+          throw new sdk.CallEmbedError(
+            "invalid_queue",
+            "queue is required (pass queue on the provider, button, or start())."
+          );
+        }
+        setError(null);
+        setMutedState(false);
+        const userOn = options.on;
+        const call = await sdk.CallEmbed.startCall({
+          ...options,
+          queue: q,
+          hidePanel: true,
+          on: {
+            ...userOn,
+            statusChange: (payload) => {
+              setStatus(payload.status);
+              userOn?.statusChange?.(payload);
+            },
+            muteChange: (payload) => {
+              setMutedState(payload.muted);
+              userOn?.muteChange?.(payload);
+            },
+            error: (payload) => {
+              setError({ code: payload.code, message: payload.message });
+              setStatus("error");
+              if (payload.callId && payload.callId !== "pending") {
+                setCallId(payload.callId);
+              }
+              userOn?.error?.(payload);
+            },
+            ended: (payload) => {
+              setStatus("ended");
+              if (payload.callId && payload.callId !== "pending") {
+                setCallId(payload.callId);
+              }
+              userOn?.ended?.(payload);
+            },
+            ringing: (payload) => {
+              setCallId(payload.callId);
+              userOn?.ringing?.(payload);
+            },
+            answered: (payload) => {
+              setCallId(payload.callId);
+              userOn?.answered?.(payload);
+            }
+          }
+        });
+        unbindRef.current?.();
+        callRef.current = call;
+        setStatus(call.status);
+        if (call.callId !== "pending") setCallId(call.callId);
+        unbindRef.current = bindCall(call, {
+          setStatus,
+          setCallId,
+          setMuted: setMutedState,
+          setError
+        });
+        return call;
+      } catch (err) {
+        const state = toErrorState(err);
+        setError(state);
+        setStatus("error");
+        if (err instanceof sdk.CallEmbedError) throw err;
+        throw new sdk.CallEmbedError("call_failed", state.message);
+      }
+    },
+    [queue]
+  );
+  const end = react.useCallback(async () => {
+    const call = callRef.current ?? sdk.CallEmbed.getActiveCall();
+    if (!call) {
+      setStatus("idle");
+      return;
+    }
+    await call.hangUp();
+  }, []);
+  const setMuted = react.useCallback(async (next) => {
+    const call = callRef.current ?? sdk.CallEmbed.getActiveCall();
+    if (!call) {
+      setMutedState(next);
+      return;
+    }
+    await call.setMuted(next);
+  }, []);
+  const value = react.useMemo(
+    () => ({
+      status,
+      uiState: toUiState(status),
+      callId,
+      muted,
+      error,
+      locale: resolvedLocale,
+      start,
+      end,
+      setMuted,
+      defaultQueue: queue
+    }),
+    [status, callId, muted, error, resolvedLocale, start, end, setMuted, queue]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(CallEmbedReactContext.Provider, { value, children });
+}
+function useCallEmbed() {
+  const ctx = react.useContext(CallEmbedReactContext);
+  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
+  };
+}
+function CallEmbedButton({
+  queue,
+  label,
+  metadata,
+  displayName,
+  showStatus = true,
+  showMute = true,
+  onError,
+  className,
+  disabled,
+  ...rest
+}) {
+  const embed = useCallEmbed();
+  const [busy, setBusy] = react.useState(false);
+  const copy = react.useMemo(
+    () => ui.resolveCopy(runtimeForCopy(embed.locale)),
+    [embed.locale]
+  );
+  const inCall = embed.uiState === "ringing" || embed.uiState === "connected";
+  const buttonLabel = inCall ? copy.hangup : label ?? copy.launchDefault;
+  const statusText = react.useMemo(() => {
+    if (embed.uiState === "error" && embed.error) {
+      return ui.friendlyErrorMessage(copy, embed.error.code, embed.error.message);
+    }
+    return statusLabel(copy, embed.uiState, embed.status);
+  }, [copy, embed.error, embed.status, embed.uiState]);
+  const tone = embed.uiState === "error" ? "error" : embed.uiState === "connected" ? "ok" : void 0;
+  const onClick = react.useCallback(async () => {
+    setBusy(true);
+    try {
+      if (inCall) {
+        await embed.end();
+      } else {
+        await embed.start({
+          queue: queue ?? embed.defaultQueue,
+          metadata,
+          displayName
+        });
+      }
+    } catch (err) {
+      const ce = err instanceof sdk.CallEmbedError ? err : new sdk.CallEmbedError(
+        "call_failed",
+        err instanceof Error ? err.message : String(err)
+      );
+      onError?.(ce);
+    } finally {
+      setBusy(false);
+    }
+  }, [displayName, embed, inCall, metadata, onError, queue]);
+  const onMuteClick = react.useCallback(async () => {
+    setBusy(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)
+      );
+      onError?.(ce);
+    } finally {
+      setBusy(false);
+    }
+  }, [embed, onError]);
+  const rootClass = ["ce-react-root", className].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: rootClass, "data-ce-react": "", children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "button",
+      {
+        type: "button",
+        className: "ce-react-button",
+        "data-state": embed.uiState,
+        ...rest,
+        disabled: disabled || busy,
+        "aria-busy": busy || void 0,
+        onClick: () => {
+          void onClick();
+        },
+        children: buttonLabel
+      }
+    ),
+    showMute && inCall ? /* @__PURE__ */ jsxRuntime.jsx(
+      "button",
+      {
+        type: "button",
+        className: "ce-react-mute",
+        disabled: busy,
+        onClick: () => {
+          void onMuteClick();
+        },
+        children: embed.muted ? copy.unmute : copy.mute
+      }
+    ) : null,
+    showStatus ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: "ce-react-status", "data-tone": tone, "data-state": embed.uiState, children: statusText }) : null
+  ] });
+}
+
+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.CallEmbedButton = CallEmbedButton;
+exports.CallEmbedProvider = CallEmbedProvider;
+exports.statusLabel = statusLabel;
+exports.toUiState = toUiState;
+exports.useCallEmbed = useCallEmbed;

package/dist/index.d.cts

@@ -0,0 +1,86 @@
+import { ReactNode, ButtonHTMLAttributes } from 'react';
+import { CallStatus, Locale, StartCallOptions, ActiveCall, InitOptions, CallEmbedError } from '@callembed/sdk';
+export { ActiveCall, CallStatus, InitOptions, Locale, StartCallOptions } from '@callembed/sdk';
+import { PanelCopy } from '@callembed/sdk/ui';
+export { PanelCopy, enCopy, friendlyErrorMessage, resolveCopy, zhTwCopy } from '@callembed/sdk/ui';
+
+/**
+ * Simplified UI lifecycle for `<CallEmbedButton />`.
+ * Maps onto SDK {@link CallStatus}:
+ * - `connecting` | `ringing` → `ringing`
+ * - `answered` → `connected`
+ */
+type CallEmbedUiState = "idle" | "ringing" | "connected" | "ended" | "error";
+declare function toUiState(status: CallStatus | "idle"): CallEmbedUiState;
+interface CallEmbedErrorState {
+    code: string;
+    message: string;
+}
+interface CallEmbedContextValue {
+    /** SDK call status (includes `connecting` / `answered`). */
+    status: CallStatus | "idle";
+    /** Button-oriented status (`answered` → `connected`). */
+    uiState: CallEmbedUiState;
+    callId: string | null;
+    muted: boolean;
+    error: CallEmbedErrorState | null;
+    locale: Locale;
+    /** Start a queue call (customer-service ring → agent answers). */
+    start: (options?: Partial<StartCallOptions> & {
+        queue?: string;
+    }) => Promise<ActiveCall>;
+    /** Hang up the active call (idempotent). */
+    end: () => Promise<void>;
+    setMuted: (muted: boolean) => Promise<void>;
+    /** Default queue from the provider when button/hook omit `queue`. */
+    defaultQueue: string | undefined;
+}
+type CallEmbedProviderProps = InitOptions & {
+    children: ReactNode;
+    /**
+     * Default queue name for `<CallEmbedButton />` / `useCallEmbed().start()`
+     * when callers omit `queue`.
+     */
+    queue?: string;
+};
+
+/**
+ * Initializes `@callembed/sdk` once for the subtree and exposes call state.
+ * Safe for Next.js App Router: no `window` access at module evaluate time;
+ * `CallEmbed.init` runs in `useEffect`.
+ *
+ * Unmount or `publishableKey` / `apiBaseUrl` change hangs up any active call
+ * so an SPA route change cannot leave a billed call running.
+ */
+declare function CallEmbedProvider({ children, publishableKey, apiBaseUrl, locale, copy, branding, debug, queue, }: CallEmbedProviderProps): ReactNode;
+/**
+ * Access CallEmbed state and controls. Must be used under {@link CallEmbedProvider}.
+ */
+declare function useCallEmbed(): CallEmbedContextValue;
+
+interface CallEmbedButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "children" | "onError"> {
+    /** Queue to ring. Falls back to `CallEmbedProvider` `queue`. */
+    queue?: string;
+    /** Idle-state label; defaults to locale `launchDefault`. */
+    label?: string;
+    /** Optional metadata forwarded to `startCall`. */
+    metadata?: Record<string, unknown>;
+    /** Optional caller display name. */
+    displayName?: string;
+    /** Show a status line under the button. Default: `true`. */
+    showStatus?: boolean;
+    /** Show mute control while ringing/connected. Default: `true`. */
+    showMute?: boolean;
+    /** Called when start/end rejects. */
+    onError?: (error: CallEmbedError) => void;
+}
+/**
+ * Start / end call button for a customer-service queue.
+ * States: `idle` → `ringing` → `connected` → `ended` | `error`.
+ */
+declare function CallEmbedButton({ queue, label, metadata, displayName, showStatus, showMute, onError, className, disabled, ...rest }: CallEmbedButtonProps): ReactNode;
+
+/** Status line for the React button / hook consumers. */
+declare function statusLabel(copy: PanelCopy, uiState: CallEmbedUiState, sdkStatus: string): string;
+
+export { CallEmbedButton, type CallEmbedButtonProps, type CallEmbedContextValue, type CallEmbedErrorState, CallEmbedProvider, type CallEmbedProviderProps, type CallEmbedUiState, statusLabel, toUiState, useCallEmbed };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { ReactNode, ButtonHTMLAttributes } from 'react';
+import { CallStatus, Locale, StartCallOptions, ActiveCall, InitOptions, CallEmbedError } from '@callembed/sdk';
+export { ActiveCall, CallStatus, InitOptions, Locale, StartCallOptions } from '@callembed/sdk';
+import { PanelCopy } from '@callembed/sdk/ui';
+export { PanelCopy, enCopy, friendlyErrorMessage, resolveCopy, zhTwCopy } from '@callembed/sdk/ui';
+
+/**
+ * Simplified UI lifecycle for `<CallEmbedButton />`.
+ * Maps onto SDK {@link CallStatus}:
+ * - `connecting` | `ringing` → `ringing`
+ * - `answered` → `connected`
+ */
+type CallEmbedUiState = "idle" | "ringing" | "connected" | "ended" | "error";
+declare function toUiState(status: CallStatus | "idle"): CallEmbedUiState;
+interface CallEmbedErrorState {
+    code: string;
+    message: string;
+}
+interface CallEmbedContextValue {
+    /** SDK call status (includes `connecting` / `answered`). */
+    status: CallStatus | "idle";
+    /** Button-oriented status (`answered` → `connected`). */
+    uiState: CallEmbedUiState;
+    callId: string | null;
+    muted: boolean;
+    error: CallEmbedErrorState | null;
+    locale: Locale;
+    /** Start a queue call (customer-service ring → agent answers). */
+    start: (options?: Partial<StartCallOptions> & {
+        queue?: string;
+    }) => Promise<ActiveCall>;
+    /** Hang up the active call (idempotent). */
+    end: () => Promise<void>;
+    setMuted: (muted: boolean) => Promise<void>;
+    /** Default queue from the provider when button/hook omit `queue`. */
+    defaultQueue: string | undefined;
+}
+type CallEmbedProviderProps = InitOptions & {
+    children: ReactNode;
+    /**
+     * Default queue name for `<CallEmbedButton />` / `useCallEmbed().start()`
+     * when callers omit `queue`.
+     */
+    queue?: string;
+};
+
+/**
+ * Initializes `@callembed/sdk` once for the subtree and exposes call state.
+ * Safe for Next.js App Router: no `window` access at module evaluate time;
+ * `CallEmbed.init` runs in `useEffect`.
+ *
+ * Unmount or `publishableKey` / `apiBaseUrl` change hangs up any active call
+ * so an SPA route change cannot leave a billed call running.
+ */
+declare function CallEmbedProvider({ children, publishableKey, apiBaseUrl, locale, copy, branding, debug, queue, }: CallEmbedProviderProps): ReactNode;
+/**
+ * Access CallEmbed state and controls. Must be used under {@link CallEmbedProvider}.
+ */
+declare function useCallEmbed(): CallEmbedContextValue;
+
+interface CallEmbedButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "children" | "onError"> {
+    /** Queue to ring. Falls back to `CallEmbedProvider` `queue`. */
+    queue?: string;
+    /** Idle-state label; defaults to locale `launchDefault`. */
+    label?: string;
+    /** Optional metadata forwarded to `startCall`. */
+    metadata?: Record<string, unknown>;
+    /** Optional caller display name. */
+    displayName?: string;
+    /** Show a status line under the button. Default: `true`. */
+    showStatus?: boolean;
+    /** Show mute control while ringing/connected. Default: `true`. */
+    showMute?: boolean;
+    /** Called when start/end rejects. */
+    onError?: (error: CallEmbedError) => void;
+}
+/**
+ * Start / end call button for a customer-service queue.
+ * States: `idle` → `ringing` → `connected` → `ended` | `error`.
+ */
+declare function CallEmbedButton({ queue, label, metadata, displayName, showStatus, showMute, onError, className, disabled, ...rest }: CallEmbedButtonProps): ReactNode;
+
+/** Status line for the React button / hook consumers. */
+declare function statusLabel(copy: PanelCopy, uiState: CallEmbedUiState, sdkStatus: string): string;
+
+export { CallEmbedButton, type CallEmbedButtonProps, type CallEmbedContextValue, type CallEmbedErrorState, CallEmbedProvider, type CallEmbedProviderProps, type CallEmbedUiState, statusLabel, toUiState, useCallEmbed };

package/dist/index.js

@@ -0,0 +1,350 @@
+"use client";
+import { CallEmbed, CallEmbedError } from '@callembed/sdk';
+import { createContext, useState, useRef, useCallback, useEffect, useMemo, useContext } from 'react';
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { resolveCopy, friendlyErrorMessage } from '@callembed/sdk/ui';
+export { enCopy, friendlyErrorMessage, resolveCopy, zhTwCopy } from '@callembed/sdk/ui';
+
+// src/context.tsx
+
+// 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 CallEmbedReactContext = createContext(null);
+function toErrorState(err) {
+  if (err instanceof 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());
+  };
+}
+function CallEmbedProvider({
+  children,
+  publishableKey,
+  apiBaseUrl,
+  locale,
+  copy,
+  branding,
+  debug,
+  queue
+}) {
+  const [status, setStatus] = useState("idle");
+  const [callId, setCallId] = useState(null);
+  const [muted, setMutedState] = useState(false);
+  const [error, setError] = useState(null);
+  const [resolvedLocale, setResolvedLocale] = useState(locale ?? "en");
+  const callRef = useRef(null);
+  const unbindRef = useRef(null);
+  const copyKey = JSON.stringify(copy ?? {});
+  const hangUpActive = useCallback(() => {
+    unbindRef.current?.();
+    unbindRef.current = null;
+    const call = callRef.current ?? CallEmbed.getActiveCall();
+    callRef.current = null;
+    if (call && isActiveStatus(call.status)) {
+      void call.hangUp();
+    }
+  }, []);
+  useEffect(() => {
+    try {
+      CallEmbed.init({
+        publishableKey,
+        apiBaseUrl,
+        locale,
+        copy,
+        branding,
+        debug
+      });
+      const runtime = CallEmbed._getRuntime();
+      if (runtime) setResolvedLocale(runtime.locale);
+    } catch (err) {
+      const state = toErrorState(err);
+      setError(state);
+      setStatus("error");
+    }
+  }, [publishableKey, apiBaseUrl, locale, copyKey, branding, debug]);
+  useEffect(() => {
+    return () => {
+      hangUpActive();
+    };
+  }, [publishableKey, apiBaseUrl, hangUpActive]);
+  const start = useCallback(
+    async (options = {}) => {
+      try {
+        const q = options.queue ?? queue;
+        if (!q?.trim()) {
+          throw new CallEmbedError(
+            "invalid_queue",
+            "queue is required (pass queue on the provider, button, or start())."
+          );
+        }
+        setError(null);
+        setMutedState(false);
+        const userOn = options.on;
+        const call = await CallEmbed.startCall({
+          ...options,
+          queue: q,
+          hidePanel: true,
+          on: {
+            ...userOn,
+            statusChange: (payload) => {
+              setStatus(payload.status);
+              userOn?.statusChange?.(payload);
+            },
+            muteChange: (payload) => {
+              setMutedState(payload.muted);
+              userOn?.muteChange?.(payload);
+            },
+            error: (payload) => {
+              setError({ code: payload.code, message: payload.message });
+              setStatus("error");
+              if (payload.callId && payload.callId !== "pending") {
+                setCallId(payload.callId);
+              }
+              userOn?.error?.(payload);
+            },
+            ended: (payload) => {
+              setStatus("ended");
+              if (payload.callId && payload.callId !== "pending") {
+                setCallId(payload.callId);
+              }
+              userOn?.ended?.(payload);
+            },
+            ringing: (payload) => {
+              setCallId(payload.callId);
+              userOn?.ringing?.(payload);
+            },
+            answered: (payload) => {
+              setCallId(payload.callId);
+              userOn?.answered?.(payload);
+            }
+          }
+        });
+        unbindRef.current?.();
+        callRef.current = call;
+        setStatus(call.status);
+        if (call.callId !== "pending") setCallId(call.callId);
+        unbindRef.current = bindCall(call, {
+          setStatus,
+          setCallId,
+          setMuted: setMutedState,
+          setError
+        });
+        return call;
+      } catch (err) {
+        const state = toErrorState(err);
+        setError(state);
+        setStatus("error");
+        if (err instanceof CallEmbedError) throw err;
+        throw new CallEmbedError("call_failed", state.message);
+      }
+    },
+    [queue]
+  );
+  const end = useCallback(async () => {
+    const call = callRef.current ?? CallEmbed.getActiveCall();
+    if (!call) {
+      setStatus("idle");
+      return;
+    }
+    await call.hangUp();
+  }, []);
+  const setMuted = useCallback(async (next) => {
+    const call = callRef.current ?? CallEmbed.getActiveCall();
+    if (!call) {
+      setMutedState(next);
+      return;
+    }
+    await call.setMuted(next);
+  }, []);
+  const value = useMemo(
+    () => ({
+      status,
+      uiState: toUiState(status),
+      callId,
+      muted,
+      error,
+      locale: resolvedLocale,
+      start,
+      end,
+      setMuted,
+      defaultQueue: queue
+    }),
+    [status, callId, muted, error, resolvedLocale, start, end, setMuted, queue]
+  );
+  return /* @__PURE__ */ jsx(CallEmbedReactContext.Provider, { value, children });
+}
+function useCallEmbed() {
+  const ctx = useContext(CallEmbedReactContext);
+  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
+  };
+}
+function CallEmbedButton({
+  queue,
+  label,
+  metadata,
+  displayName,
+  showStatus = true,
+  showMute = true,
+  onError,
+  className,
+  disabled,
+  ...rest
+}) {
+  const embed = useCallEmbed();
+  const [busy, setBusy] = useState(false);
+  const copy = useMemo(
+    () => resolveCopy(runtimeForCopy(embed.locale)),
+    [embed.locale]
+  );
+  const inCall = embed.uiState === "ringing" || embed.uiState === "connected";
+  const buttonLabel = inCall ? copy.hangup : label ?? copy.launchDefault;
+  const statusText = useMemo(() => {
+    if (embed.uiState === "error" && embed.error) {
+      return friendlyErrorMessage(copy, embed.error.code, embed.error.message);
+    }
+    return statusLabel(copy, embed.uiState, embed.status);
+  }, [copy, embed.error, embed.status, embed.uiState]);
+  const tone = embed.uiState === "error" ? "error" : embed.uiState === "connected" ? "ok" : void 0;
+  const onClick = useCallback(async () => {
+    setBusy(true);
+    try {
+      if (inCall) {
+        await embed.end();
+      } else {
+        await embed.start({
+          queue: queue ?? embed.defaultQueue,
+          metadata,
+          displayName
+        });
+      }
+    } catch (err) {
+      const ce = err instanceof CallEmbedError ? err : new CallEmbedError(
+        "call_failed",
+        err instanceof Error ? err.message : String(err)
+      );
+      onError?.(ce);
+    } finally {
+      setBusy(false);
+    }
+  }, [displayName, embed, inCall, metadata, onError, queue]);
+  const onMuteClick = useCallback(async () => {
+    setBusy(true);
+    try {
+      await embed.setMuted(!embed.muted);
+    } catch (err) {
+      const ce = err instanceof CallEmbedError ? err : new CallEmbedError(
+        "call_failed",
+        err instanceof Error ? err.message : String(err)
+      );
+      onError?.(ce);
+    } finally {
+      setBusy(false);
+    }
+  }, [embed, onError]);
+  const rootClass = ["ce-react-root", className].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsxs("div", { className: rootClass, "data-ce-react": "", children: [
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        className: "ce-react-button",
+        "data-state": embed.uiState,
+        ...rest,
+        disabled: disabled || busy,
+        "aria-busy": busy || void 0,
+        onClick: () => {
+          void onClick();
+        },
+        children: buttonLabel
+      }
+    ),
+    showMute && inCall ? /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        className: "ce-react-mute",
+        disabled: busy,
+        onClick: () => {
+          void onMuteClick();
+        },
+        children: embed.muted ? copy.unmute : copy.mute
+      }
+    ) : null,
+    showStatus ? /* @__PURE__ */ jsx("p", { className: "ce-react-status", "data-tone": tone, "data-state": embed.uiState, children: statusText }) : null
+  ] });
+}
+
+export { CallEmbedButton, CallEmbedProvider, statusLabel, toUiState, useCallEmbed };

package/dist/styles.css

@@ -0,0 +1,89 @@
+/**
+ * Default styles for `@callembed/react`.
+ * Theme via `--ce-*` (same public tokens as `@callembed/sdk/ui`).
+ */
+:where(.ce-react-button, .ce-react-status, .ce-react-mute) {
+  font-family: var(
+    --ce-font,
+    "Noto Sans TC",
+    "IBM Plex Sans",
+    "Segoe UI",
+    sans-serif
+  );
+  color: var(--ce-fg, #e8eef4);
+}
+
+.ce-react-root {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.5rem;
+}
+
+.ce-react-button {
+  appearance: none;
+  display: inline-block;
+  border: 1px solid var(--ce-border, #2a3a46);
+  border-radius: var(--ce-radius, 0);
+  background: color-mix(in srgb, var(--ce-accent, #5eb0d8) 25%, transparent);
+  color: var(--ce-fg, #e8eef4);
+  padding: 0.7rem 1.1rem;
+  font-size: inherit;
+  cursor: pointer;
+}
+
+.ce-react-button:hover {
+  border-color: var(--ce-accent, #5eb0d8);
+}
+
+.ce-react-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.ce-react-button[data-state="ringing"],
+.ce-react-button[data-state="connected"] {
+  border-color: color-mix(
+    in srgb,
+    var(--ce-danger, #c44b4b) 55%,
+    var(--ce-border, #2a3a46)
+  );
+  color: var(--ce-error, #f0c4c4);
+  background: transparent;
+}
+
+.ce-react-status {
+  margin: 0;
+  color: var(--ce-muted, #9aadb8);
+  font-size: 0.9rem;
+  line-height: 1.4;
+  min-height: 1.25em;
+}
+
+.ce-react-status[data-tone="error"] {
+  color: var(--ce-error, #f0c4c4);
+}
+
+.ce-react-status[data-tone="ok"] {
+  color: var(--ce-ok, #9fd6c0);
+}
+
+.ce-react-mute {
+  appearance: none;
+  border: 1px solid var(--ce-border, #2a3a46);
+  border-radius: var(--ce-radius, 0);
+  background: transparent;
+  color: inherit;
+  padding: 0.45rem 0.75rem;
+  font: inherit;
+  cursor: pointer;
+}
+
+.ce-react-mute:hover {
+  border-color: var(--ce-accent, #5eb0d8);
+}
+
+.ce-react-mute:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@callembed/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "React components and hooks for CallEmbed (thin wrapper over @callembed/sdk)",
+  "license": "MIT",
+  "author": "Sealby",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./dist/styles.css"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && node ./scripts/copy-css.mjs",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pack:verify": "node ./scripts/pack-verify.mjs"
+  },
+  "homepage": "https://callembed.sealby.me",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TonyFeng1203/CallEmbed.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/TonyFeng1203/CallEmbed/issues"
+  },
+  "keywords": [
+    "callembed",
+    "react",
+    "voice",
+    "webrtc",
+    "livekit",
+    "customer-support"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@callembed/sdk": "^0.1.0",
+    "livekit-client": "^2.13.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "livekit-client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@callembed/sdk": "^0.1.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^18.3.20",
+    "@types/react-dom": "^18.3.6",
+    "jsdom": "26.1.0",
+    "livekit-client": "^2.13.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "3.2.7"
+  }
+}