kasookoo-click-to-call-widget 0.1.0-beta.0

package/README.md

@@ -0,0 +1,549 @@
+# kasookoo-click-to-call-widget
+
+A drop-in **click-to-call widget** for your website: a floating call button,
+dial pad, and in-call window, delivered as a single custom HTML element —
+`<kasookoo-dialer>`. Visitors can dial a real phone number and talk to you
+over the browser, no app or plugin required.
+
+## Why a custom element
+
+`<kasookoo-dialer>` is a [web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) —
+a real HTML element the browser understands natively, the same way it
+understands `<video>` or `<select>`. That means it works identically
+everywhere:
+
+- Drop it into a plain HTML page with one `<script>` tag, no build step.
+- Drop it into a React, Angular, Vue, or Svelte app — every framework already
+  has its own normal way of placing a DOM element on the page and reading
+  values off it (a `ref`, a template binding, etc.). Nothing framework-specific
+  needs to be installed or maintained.
+- Use as many of them as you want, anywhere in your app — one shared
+  connection backs every tag (see [Connecting once](#connecting-once) below).
+
+Each tag is entirely self-contained: its own look, its own dial pad, its own
+in-call window. It does not use or expose any of your page's CSS, and your
+page's CSS cannot accidentally break it either.
+
+## Install
+
+**Via npm** (bundler-based apps — React, Angular, Vue, Svelte, etc.):
+
+```bash
+npm install kasookoo-click-to-call-widget
+```
+
+```js
+import "kasookoo-click-to-call-widget" // registers <kasookoo-dialer>
+```
+
+**Via a plain `<script>` tag** (no build step, no npm):
+
+```html
+<script type="module" src="https://unpkg.com/kasookoo-click-to-call-widget/dist/kasookoo-dialer.js"></script>
+```
+
+## Connecting once
+
+Call `KasookooClickToCall.init()` **once**, anywhere early in your app —
+before or after your `<kasookoo-dialer>` tags render, it doesn't matter which
+comes first. Every tag on the page automatically shares the one connection
+this creates, so tags themselves don't take a publishable key or a caller
+name:
+
+```js
+import { KasookooClickToCall } from "kasookoo-click-to-call-widget"
+
+await KasookooClickToCall.init({
+  publishableKey: "pk_live_...",
+  subject: "Website visitor", // a display name for whoever is placing calls — see below
+})
+```
+
+- `publishableKey` — the key you were given for your website/app.
+- `subject` — a display name for the caller. Any name is fine (e.g.
+  `"Website visitor"`, or a logged-in user's name) — it does not need to be
+  an email address or match an account.
+
+Calling `init()` more than once is harmless — later calls just resolve to the
+same connection the first call set up, so it's safe to call it from a
+component that might mount more than once.
+
+## Quick start
+
+```html
+<kasookoo-dialer></kasookoo-dialer>
+```
+
+That's it — this renders a small floating call button. Clicking it opens a
+popup with the full dial pad; when a visitor enters a number and presses
+call, the widget places the call and shows a floating in-call card with
+mute/hang-up controls, automatically.
+
+## Static "call this number" buttons
+
+Set `fixed-number` on a tag to turn it into a button for one specific number
+instead of a dial pad. Instead of a dots icon, it shows the number itself as
+its label, calls that number directly on click (behind a confirmation modal
+by default), and shows a small call icon beside the number on hover:
+
+```html
+<!-- Dynamic (default): visitor dials any number -->
+<kasookoo-dialer></kasookoo-dialer>
+
+<!-- Static: shows "+1 800 555 1234", confirms, then calls it -->
+<kasookoo-dialer fixed-number="+1 800 555 1234"></kasookoo-dialer>
+```
+
+Two more attributes only apply to a static tag — both default to on:
+
+```html
+<!-- No confirmation modal, no hover icon: one click, dials immediately -->
+<kasookoo-dialer
+  fixed-number="+18005551234"
+  confirm-before-call="false"
+  show-call-icon-on-hover="false"
+></kasookoo-dialer>
+```
+
+The number is dialed exactly as you write it in `fixed-number` (spaces and
+formatting are stripped automatically before it's actually dialed) — so
+format it however reads best to a visitor.
+
+## One call at a time
+
+Every `<kasookoo-dialer>` tag on the page — dynamic or static — shares the
+same active-call state. If a visitor is already on a call and tries to start
+another one from any tag, the widget doesn't place a second call: it fires a
+`call-error` event with `code: "call_in_progress"` on the tag they just
+clicked, and every other tag's button disables itself for the duration of
+the active call.
+
+## Placing a call programmatically
+
+A static tag covers the common case — a button that always calls the same
+number, no JavaScript required. For a number that isn't known until runtime
+(looked up from an API, chosen per click, etc.), call the element's `dial`
+method directly instead:
+
+```html
+<kasookoo-dialer id="ctc"></kasookoo-dialer>
+<button id="call-support">Call support for my region</button>
+
+<script type="module">
+  document.getElementById("call-support").addEventListener("click", async () => {
+    const number = await resolveSupportNumberForVisitor() // your own logic
+    document.getElementById("ctc").dial(number)
+  })
+</script>
+```
+
+On a tag that has `fixed-number` set, `dial()` ignores whatever you pass it
+and always calls that configured number instead — a static tag's whole point
+is to only ever call the one number it's configured for.
+
+The in-call window renders the same way regardless of how the call started —
+`dial()`, a static button, and a number typed into the dial pad all go
+through the same code path.
+
+## The widget instance
+
+`init()` resolves to a `KasookooClickToCall` instance. It does **not** offer
+any way to place a call from code — a real user clicking a rendered
+`<kasookoo-dialer>` tag is the only way a call gets placed. This is
+deliberate: if placing a call were just a normal method call, any script on
+the page (a compromised dependency, an injected ad script) could silently
+dial numbers with no user interaction and no confirmation. What the instance
+does offer is read-only inspection and teardown:
+
+```js
+const widget = await KasookooClickToCall.init({ publishableKey: "pk_live_...", subject: "Website visitor" })
+
+widget.session      // SessionInfo | null — sessionId, subject, organizationId, expiresAt
+widget.activeCall   // Call | null — the call currently connecting/connected, if any (see below)
+widget.close()      // tears the widget down: ends any active call, removes every mounted
+                     // <kasookoo-dialer> trigger button, clears the session. Safe to call more
+                     // than once; the instance can't be reused afterward — a later init() call
+                     // creates a fresh one.
+```
+
+### The `Call` object
+
+`activeCall` returns a `Call` — the same object that drives every
+`<kasookoo-dialer>`'s built-in call window internally:
+
+| Member | Type | Description |
+|---|---|---|
+| `roomName` | `string` | Call/room identifier. |
+| `callTraceId` | `string` | Stable id for this call's lifecycle — useful for correlating logs/support requests. |
+| `remote` | `{ name: string, type?: string, id?: string }` | The other side of the call — `name` is the dialed phone number. |
+| `state` | `CallState` | `"connecting" \| "connected" \| "ended"`. |
+| `muted` | `boolean` | Whether the local microphone is muted. |
+| `setMuted(muted)` | `(muted: boolean) => Promise<void>` | Mutes/unmutes the local microphone. |
+| `end()` | `() => Promise<void>` | Hangs up, whether or not the phone number has answered yet. |
+| `on("state", cb)` | `(state: CallState) => void` | Fires on every state transition. |
+| `on("error", cb)` | `(err: KasookooError) => void` | Fires if something goes wrong on this specific call. |
+
+## Configuration
+
+Two kinds of settings:
+
+- **Simple values** go on the element as plain HTML attributes (kebab-case,
+  since HTML attributes can only hold text):
+  - `fixed-number` — optional. See [Static "call this number" buttons](#static-call-this-number-buttons).
+  - `confirm-before-call` — static tags only, defaults to on. Set to `"false"` to skip the confirmation modal.
+  - `show-call-icon-on-hover` — static tags only, defaults to on. Set to `"false"` to hide the hover icon.
+
+- **Everything else** (an object) goes on the element's `config` **property**
+  in JavaScript, since HTML attributes can't hold objects:
+
+```js
+const dialer = document.querySelector("kasookoo-dialer")
+dialer.config = {
+  participantName: "Jane (Sales Inquiry)", // shown as the caller's name on the call, defaults to the `subject` given to init()
+  defaultCountryCode: "+1",                // prefilled in the dial pad's number field (dynamic tags only)
+  placeholder: "Enter phone number",       // dial pad input placeholder (dynamic tags only)
+  customCss: ".kasookoo-ctc-trigger--static { background: #7c3aed; }", // see Styling below
+}
+```
+
+## Styling
+
+Set `config.customCss` to a raw CSS string to restyle a tag — it's injected
+into that tag's own shadow root, so it only ever affects that one tag's
+trigger button, dial pad, and (static tags) confirmation modal. It does not
+reach the floating in-call window, since that's shared, page-level UI
+independent of any single tag.
+
+If you use Tailwind or another CSS build step, compile it and pass the
+resulting CSS text here — this widget's shadow root isn't part of your page's
+normal build output, so utility classes from your app's stylesheet can't
+reach in on their own.
+
+```js
+dialer.config = {
+  customCss: `
+    .kasookoo-ctc-trigger--static { background: #7c3aed; border-radius: 8px; }
+    .kasookoo-ctc-trigger--static:hover { background: #6d28d9; }
+  `,
+}
+```
+
+## Listening for call activity
+
+The element reports what's happening through standard browser
+[`CustomEvent`s](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) —
+listen with `addEventListener`, same as any other DOM event:
+
+```js
+const dialer = document.querySelector("kasookoo-dialer")
+
+dialer.addEventListener("call-state", (e) => {
+  // e.detail = { state: "connecting" | "connected" | "ended", phoneNumber: string }
+  console.log("call is now", e.detail.state)
+})
+
+dialer.addEventListener("call-error", (e) => {
+  // e.detail = { code: string, message: string }
+  console.warn("something went wrong:", e.detail.message)
+})
+
+dialer.addEventListener("session-expired", () => {
+  console.warn("the widget's session expired and needs a page refresh")
+})
+```
+
+`call-state` fires for every step of a call's life: `"connecting"` while it's
+dialing, `"connected"` once answered, `"ended"` when it's over. Every call
+placed by this widget is outbound — there is no "incoming call" state.
+
+## Framework usage
+
+### Plain HTML / vanilla JS
+
+```html
+<script type="module" src="https://unpkg.com/kasookoo-click-to-call-widget/dist/kasookoo-dialer.js"></script>
+
+<!-- Dynamic: dots icon, opens the dial pad -->
+<kasookoo-dialer id="ctc"></kasookoo-dialer>
+
+<!-- Static: shows the number, calls it on click -->
+<kasookoo-dialer fixed-number="+18005551234"></kasookoo-dialer>
+
+<script type="module">
+  import { KasookooClickToCall } from "https://unpkg.com/kasookoo-click-to-call-widget/dist/kasookoo-dialer.js"
+
+  await KasookooClickToCall.init({ publishableKey: "pk_live_...", subject: "Website visitor" })
+
+  const dialer = document.getElementById("ctc")
+  dialer.config = { defaultCountryCode: "+1" }
+  dialer.addEventListener("call-state", (e) => console.log("call state:", e.detail.state))
+</script>
+```
+
+### React
+
+```tsx
+import { useEffect, useState } from "react"
+import { KasookooClickToCall } from "kasookoo-click-to-call-widget" // registers <kasookoo-dialer> once
+
+// Call init() once, high in your app (e.g. a top-level effect) — every
+// <kasookoo-dialer> tag rendered anywhere afterward shares that connection.
+function App() {
+  const [ready, setReady] = useState(false)
+
+  useEffect(() => {
+    KasookooClickToCall.init({ publishableKey: "pk_live_...", subject: "Website visitor" }).then(() =>
+      setReady(true)
+    )
+  }, [])
+
+  if (!ready) return null
+  return (
+    <>
+      {/* @ts-expect-error -- custom element, not a typed JSX component */}
+      <kasookoo-dialer />
+      {/* Static button needs no ref or click handler — the tag is the whole button: */}
+      {/* @ts-expect-error -- custom element, not a typed JSX component */}
+      <kasookoo-dialer fixed-number="+18005551234" />
+    </>
+  )
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <!-- Dynamic -->
+  <kasookoo-dialer ref="dialerEl" @call-state="onCallState" />
+  <!-- Static: shows the number, calls it on click -->
+  <kasookoo-dialer fixed-number="+18005551234" />
+</template>
+
+<script setup>
+import { ref, onMounted } from "vue"
+import { KasookooClickToCall } from "kasookoo-click-to-call-widget"
+
+const dialerEl = ref(null)
+const onCallState = (e) => console.log("call state:", e.detail.state)
+
+onMounted(async () => {
+  await KasookooClickToCall.init({ publishableKey: "pk_live_...", subject: "Website visitor" })
+  dialerEl.value.config = { defaultCountryCode: "+1" }
+})
+</script>
+```
+
+Vue treats unrecognized tags with a dash in the name as custom elements
+automatically — no extra configuration needed.
+
+### Angular
+
+```html
+<!-- Dynamic -->
+<kasookoo-dialer #ctc (call-state)="onCallState($event)"></kasookoo-dialer>
+<!-- Static: shows the number, calls it on click -->
+<kasookoo-dialer fixed-number="+18005551234"></kasookoo-dialer>
+```
+
+```ts
+// In the module bootstrapping this component:
+// schemas: [CUSTOM_ELEMENTS_SCHEMA]
+import { KasookooClickToCall } from "kasookoo-click-to-call-widget"
+
+@Component({ /* ... */ })
+export class ClickToCallComponent implements OnInit {
+  async ngOnInit() {
+    await KasookooClickToCall.init({ publishableKey: "pk_live_...", subject: "Website visitor" })
+  }
+  onCallState(e: CustomEvent) {
+    console.log("call state:", e.detail.state)
+  }
+}
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { onMount } from "svelte"
+  import { KasookooClickToCall } from "kasookoo-click-to-call-widget"
+
+  onMount(() => {
+    KasookooClickToCall.init({ publishableKey: "pk_live_...", subject: "Website visitor" })
+  })
+</script>
+
+<!-- Dynamic -->
+<kasookoo-dialer on:call-state={(e) => console.log("call state:", e.detail.state)} />
+<!-- Static: shows the number, calls it on click -->
+<kasookoo-dialer fixed-number="+18005551234" />
+```
+
+The pattern is the same everywhere: `KasookooClickToCall.init()` is called
+once per app, plain text values are HTML attributes, anything more complex
+is a JS property set on the element (via `ref`, `:prop`, `[prop]`, or plain
+binding, depending on your framework), and anything the widget needs to tell
+you comes back as a `CustomEvent`.
+
+## Requirements
+
+- A modern browser (Chrome, Edge, Firefox, Safari — recent versions).
+- The page must be served over **HTTPS** (or `localhost` during development)
+  — browsers only allow microphone access on secure origins.
+- The visitor will be prompted to allow microphone access the first time
+  `init()` runs; a call cannot be placed without it.
+
+## What this widget does not do
+
+- It does not receive incoming calls — it only places outbound calls to
+  phone numbers.
+- It does not offer a way to swap in your own dial pad or call window design
+  — both are fixed, built-in UI (though a static tag's trigger button and
+  dial pad can be restyled — see [Styling](#styling)).
+- It does not support call hold, DTMF tones (in-call keypad input), or
+  choosing a specific microphone device.
+
+## API Reference
+
+### `KasookooClickToCall.init(config)`
+
+Called once per app, before or after your `<kasookoo-dialer>` tags render.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `publishableKey` | `string` | *required* | The key you were given for your website/app. |
+| `subject` | `string` | *required* | Display name for whoever is placing calls. Any name works — not required to be an email or match an account. |
+| `callRingTimeoutMs` | `number \| false` | `60000` | How long an unanswered call rings before it's cancelled automatically. Pass `false` to disable — the call then rings until answered or manually ended. |
+| `logging` | `KasookooLoggingConfig` | `-` | Structured JSON console logging. See below. |
+| `telemetry` | `KasookooTelemetryConfig` | `-` | **Optional** OpenTelemetry trace/log export — off unless you turn it on. See below. |
+
+`logging` options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `true` | Set to `false` to silence all console logging. |
+| `level` | `"debug" \| "info" \| "warn" \| "error"` | `"info"` | Minimum level emitted. |
+| `service` | `string` | `"kasookoo-click-to-call-widget"` | Logical service name attached to each log line. |
+| `host` | `string` | `window.location.hostname` | Host label attached to each log line. |
+
+Log lines are structured JSON emitted via `console.debug`/`info`/`warn`/`error`. Sensitive fields (tokens, passwords, secrets, etc.) are automatically redacted before logging.
+
+```js
+await KasookooClickToCall.init({
+  publishableKey: "pk_live_...",
+  subject: "Website visitor",
+  logging: { enabled: false }, // or e.g. { level: "warn" }
+})
+```
+
+`telemetry` — **entirely optional, off by default.** The widget works
+exactly the same with or without it; nothing here affects calling. Turning
+it on sends OpenTelemetry traces (every `fetch()` the widget makes, tagged
+with the same correlation ids as `logging`) and, optionally, the same
+structured logs, to a collector you control.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `false` | Turns telemetry on. Everything below only matters if this is `true`. |
+| `endpoint` | `string` | `"https://monitoring-test.kasookoo.ai/v1/traces"` | OTLP/HTTP traces endpoint. Defaults to a shared test/demo collector — good enough to `{ enabled: true }` and immediately see traces, but point this at your own collector for anything real. |
+| `logsEndpoint` | `string` | derived from `endpoint` | OTLP/HTTP logs endpoint. Defaults to `endpoint` with a trailing `/v1/traces` swapped for `/v1/logs`; set explicitly if your collector doesn't follow that convention. |
+| `serviceName` | `string` | `"kasookoo-click-to-call-widget"` | OTel `service.name`. |
+| `environment` | `string` | `"production"` | OTel `deployment.environment`. |
+
+Two things make this safe to leave off, and safe to turn on without it ever
+breaking the widget:
+
+- **It requires extra packages you install yourself.** Traces need
+  `@opentelemetry/sdk-trace-web`, `@opentelemetry/sdk-trace-base`,
+  `@opentelemetry/exporter-trace-otlp-http`, `@opentelemetry/instrumentation`,
+  `@opentelemetry/instrumentation-fetch`, `@opentelemetry/resources`,
+  `@opentelemetry/semantic-conventions`, and `@opentelemetry/api`. Log export
+  additionally needs `@opentelemetry/sdk-logs` and
+  `@opentelemetry/exporter-logs-otlp-http`. They're declared as optional
+  `peerDependencies` — npm won't install them for you, and won't complain if
+  you don't:
+
+  ```bash
+  npm install @opentelemetry/api @opentelemetry/sdk-trace-web @opentelemetry/sdk-trace-base \
+    @opentelemetry/exporter-trace-otlp-http @opentelemetry/instrumentation \
+    @opentelemetry/instrumentation-fetch @opentelemetry/resources \
+    @opentelemetry/semantic-conventions @opentelemetry/sdk-logs \
+    @opentelemetry/exporter-logs-otlp-http
+  ```
+
+  If `telemetry.enabled` is `true` but these aren't installed, the widget
+  logs a console warning and continues working with console logging only —
+  it never throws or blocks a call.
+
+- **It's bundler-only** — available when you `npm install` the widget, not
+  via the plain `<script type="module">`/CDN build. A script tag has no way
+  to resolve npm package names, so `dist/kasookoo-dialer.js` doesn't include
+  telemetry at all, on or off.
+
+```js
+// Demo — traces go to the shared test collector, no setup required:
+await KasookooClickToCall.init({
+  publishableKey: "pk_live_...",
+  subject: "Website visitor",
+  telemetry: { enabled: true },
+})
+
+// Production — point it at your own collector:
+await KasookooClickToCall.init({
+  publishableKey: "pk_live_...",
+  subject: "Website visitor",
+  telemetry: {
+    enabled: true,
+    endpoint: "https://your-collector.example.com/v1/traces",
+  },
+})
+```
+
+### `KasookooClickToCall` instance
+
+The object `init()` resolves to. See [The widget instance](#the-widget-instance). There is deliberately no way to place a call from this object — only a real user clicking a rendered `<kasookoo-dialer>` tag can do that.
+
+| Member | Type | Description |
+|---|---|---|
+| `session` | `SessionInfo \| null` | Current session info — `sessionId`, `subject`, `organizationId`, `expiresAt`. |
+| `activeCall` | `Call \| null` | The call currently connecting/connected, if any. |
+| `close()` | `() => void` | Tears the widget down: ends any active call, removes every mounted `<kasookoo-dialer>` trigger button, clears the session. Safe to call more than once. |
+
+### `<kasookoo-dialer>` attributes
+
+Plain HTML attributes — values are always strings.
+
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `fixed-number` | `string` | `-` | Presence turns this tag into a static button showing and calling this one number instead of a dial pad. |
+| `confirm-before-call` | `"false"` to disable | on | Static tags only. Shows a confirmation modal before dialing `fixed-number`. |
+| `show-call-icon-on-hover` | `"false"` to disable | on | Static tags only. Shows a call icon beside the number on hover. |
+
+### `config` property
+
+Set as a JS property (`element.config = {...}`), not an attribute — this is
+where anything beyond a plain string goes.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `participantName` | `string` | value of `subject` given to `init()` | Caller name shown on the call itself. |
+| `defaultCountryCode` | `string` | `-` | Dynamic tags only. Prefilled dialing prefix in the dial pad's number field, e.g. `"+1"`. Purely a starting value — the visitor can edit or clear it. |
+| `placeholder` | `string` | `"Enter phone number"` | Dynamic tags only. Placeholder text for the dial pad's number input. |
+| `customCss` | `string` | `-` | Raw CSS injected into this tag's own shadow root. See [Styling](#styling). |
+
+### Events
+
+Standard `CustomEvent`s — listen with `element.addEventListener(name, handler)`.
+
+| Event | Detail (`event.detail`) | Description |
+|---|---|---|
+| `call-state` | `{ state: "connecting" \| "connected" \| "ended", phoneNumber: string }` | Fires on every step of a call's life, from dialing to hang-up. |
+| `call-error` | `{ code: string, message: string }` | Fires when something goes wrong — a failed call, a denied microphone permission, a call already in progress (`code: "call_in_progress"`), etc. If `code` is `"missing_scope"`, your publishable key isn't provisioned for calling — contact your key provider/Kasookoo. |
+| `session-expired` | `{ reason: string }` | Fires if the widget's session expires mid-use; reload the page to recover. |
+
+### Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `dial` | `(phoneNumber?: string) => void` | Places a call directly, bypassing the trigger button and dial pad. On a tag with `fixed-number` set, the argument is ignored and that number is always dialed instead. |