@thunderphone/widget 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +126 -0
  2. package/package.json +8 -2
package/README.md ADDED
@@ -0,0 +1,126 @@
1
+ # @thunderphone/widget
2
+
3
+ Embed a ThunderPhone voice AI agent on any website. Users can talk to your agent directly from your site using their browser microphone.
4
+
5
+ ## Quick Start
6
+
7
+ ### Option 1: Script Tag (CDN)
8
+
9
+ No build tools required. Add two tags to your HTML:
10
+
11
+ ```html
12
+ <link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
13
+ <script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
14
+
15
+ <div id="thunderphone"></div>
16
+
17
+ <script>
18
+ ThunderPhone.mount({
19
+ element: '#thunderphone',
20
+ apiKey: 'pk_live_your_publishable_key',
21
+ agentId: 123,
22
+ })
23
+ </script>
24
+ ```
25
+
26
+ Pin to a specific version for production:
27
+
28
+ ```html
29
+ <link rel="stylesheet" href="https://cdn.thunderphone.com/widget/v0.1.0/style.css" />
30
+ <script src="https://cdn.thunderphone.com/widget/v0.1.0/widget.js"></script>
31
+ ```
32
+
33
+ ### Option 2: npm (React)
34
+
35
+ ```bash
36
+ npm install @thunderphone/widget
37
+ ```
38
+
39
+ ```tsx
40
+ import { ThunderPhoneWidget } from '@thunderphone/widget'
41
+ import '@thunderphone/widget/style.css'
42
+
43
+ function App() {
44
+ return (
45
+ <ThunderPhoneWidget
46
+ apiKey="pk_live_your_publishable_key"
47
+ agentId={123}
48
+ />
49
+ )
50
+ }
51
+ ```
52
+
53
+ ## Setup
54
+
55
+ 1. Log in to [app.thunderphone.com](https://app.thunderphone.com)
56
+ 2. Go to **Developers** to create a publishable API key and configure allowed domains
57
+ 3. Enable the **Embeddable Widget** toggle on the agent you want to expose
58
+ 4. Use the agent's ID and your publishable key in the widget code above
59
+
60
+ ## Props / Options
61
+
62
+ | Prop | Type | Required | Description |
63
+ |------|------|----------|-------------|
64
+ | `apiKey` | `string` | Yes | Your publishable API key (`pk_live_...`) |
65
+ | `agentId` | `number` | Yes | ID of the agent to connect to |
66
+ | `apiBase` | `string` | No | API base URL (defaults to `https://api.thunderphone.com/v1`) |
67
+ | `onConnect` | `() => void` | No | Called when the voice session connects |
68
+ | `onDisconnect` | `() => void` | No | Called when the session ends |
69
+ | `onError` | `(error) => void` | No | Called on errors. Error has `error` (code) and `message` fields |
70
+ | `className` | `string` | No | Additional CSS class for the widget container |
71
+
72
+ For the script tag version, pass these as properties on the options object to `ThunderPhone.mount()`, plus an `element` property (CSS selector or DOM element) for where to render.
73
+
74
+ ## Styling
75
+
76
+ The widget uses plain CSS with `tp-` prefixed classes, so it won't conflict with your styles. You can override any of these classes:
77
+
78
+ | Class | Element |
79
+ |-------|---------|
80
+ | `.tp-widget` | Outer container (inline-flex) |
81
+ | `.tp-button` | All buttons (circular, 44px) |
82
+ | `.tp-button--start` | Start/mic button |
83
+ | `.tp-button--mute` | Mute toggle button |
84
+ | `.tp-button--end` | End call button |
85
+ | `.tp-status` | Status text container |
86
+ | `.tp-status__name` | Agent name |
87
+ | `.tp-status__text` | Connection state / timer |
88
+
89
+ Example — custom colors:
90
+
91
+ ```css
92
+ .tp-button--start {
93
+ background: #4f46e5;
94
+ }
95
+ .tp-button--start:hover {
96
+ background: #4338ca;
97
+ }
98
+ ```
99
+
100
+ ## Script Tag API
101
+
102
+ `ThunderPhone.mount()` returns a handle you can use to clean up:
103
+
104
+ ```js
105
+ const widget = ThunderPhone.mount({
106
+ element: '#thunderphone',
107
+ apiKey: 'pk_live_...',
108
+ agentId: 123,
109
+ onConnect: () => console.log('Connected'),
110
+ onDisconnect: () => console.log('Disconnected'),
111
+ onError: (err) => console.error(err.message),
112
+ })
113
+
114
+ // Later, to remove the widget:
115
+ widget.unmount()
116
+ ```
117
+
118
+ ## Domain Restrictions
119
+
120
+ Your publishable key can be restricted to specific domains in the Developers settings page. Requests from unlisted domains will be rejected. `localhost` is always allowed for development.
121
+
122
+ Wildcard subdomains are supported: `*.example.com` matches `app.example.com`, `docs.example.com`, etc.
123
+
124
+ ## License
125
+
126
+ MIT
package/package.json CHANGED
@@ -1,7 +1,11 @@
1
1
  {
2
2
  "name": "@thunderphone/widget",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "Embeddable voice widget for ThunderPhone AI agents",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/autophonix/thunderphone-widget.git"
8
+ },
5
9
  "main": "dist/index.js",
6
10
  "module": "dist/index.mjs",
7
11
  "types": "dist/index.d.ts",
@@ -14,7 +18,9 @@
14
18
  "./style.css": "./dist/index.css",
15
19
  "./widget.js": "./dist/mount.global.js"
16
20
  },
17
- "files": ["dist"],
21
+ "files": [
22
+ "dist"
23
+ ],
18
24
  "scripts": {
19
25
  "build": "tsup",
20
26
  "dev": "tsup --watch"