@dudgy/podcast-widget 0.1.0

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.
package/README.md ADDED
@@ -0,0 +1,347 @@
1
+ # podcast-widget
2
+
3
+ Framework-agnostic podcast player widget with configurable player modes, CSS custom property theming, and an optional PodcastIndex API client.
4
+
5
+ Zero runtime dependencies. Ships ESM + CJS with full TypeScript declarations.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install podcast-widget
11
+ ```
12
+
13
+ ## Quick Start
14
+
15
+ ```typescript
16
+ import { AudioEngine, PlayerController, FetchEpisodeProvider, MiniPlayer, FullPlayer } from 'podcast-widget';
17
+ import 'podcast-widget/styles';
18
+
19
+ // 1. Create the core objects
20
+ const engine = new AudioEngine();
21
+ const provider = new FetchEpisodeProvider('/api/podcast-episodes', {
22
+ storagePrefix: 'podcast',
23
+ maxStoredPositions: 100,
24
+ positionSaveInterval: 5000,
25
+ skipSeconds: 30,
26
+ episodeCacheTTL: 3600000,
27
+ });
28
+ const controller = new PlayerController(engine, provider);
29
+
30
+ // 2. Create one or more player UIs
31
+ const mini = new MiniPlayer({
32
+ container: document.getElementById('mini-player')!,
33
+ controller,
34
+ controls: { playPause: true, progress: true, expand: true },
35
+ });
36
+
37
+ const full = new FullPlayer({
38
+ container: document.getElementById('full-player')!,
39
+ controller,
40
+ controls: { playPause: true, skipForward: true, skipBackward: true, volume: true, speed: true, progress: true, playlist: true },
41
+ });
42
+
43
+ // 3. Wire them together
44
+ mini.on('expand', () => full.show());
45
+ full.on('close', () => full.hide());
46
+
47
+ // 4. Load episodes
48
+ controller.loadEpisodes();
49
+ ```
50
+
51
+ ## Architecture
52
+
53
+ ```
54
+ podcast-widget/
55
+ ├── src/
56
+ │ ├── core/
57
+ │ │ ├── types.ts # Episode, PlayerConfig, events, EpisodeProvider interface
58
+ │ │ ├── event-emitter.ts # Lightweight typed event emitter
59
+ │ │ ├── audio-engine.ts # HTMLAudioElement wrapper with seek, destroy, error handling
60
+ │ │ ├── playback-storage.ts # localStorage for resume positions (namespaced keys)
61
+ │ │ ├── player-state.ts # localStorage for player state + speed preference
62
+ │ │ └── episode-provider.ts # FetchEpisodeProvider with caching + retry
63
+ │ ├── ui/
64
+ │ │ ├── utils.ts # formatTime, escapeHtml, getEpisodeImage
65
+ │ │ ├── html-templates.ts # SVG icons, playlist rendering, speed options
66
+ │ │ ├── player-controller.ts # Orchestrator: engine + storage + provider → events
67
+ │ │ ├── mini-player.ts # Mini mode with configurable controls + inline playlist
68
+ │ │ └── full-player.ts # Full modal with hero, playlist, keyboard shortcuts
69
+ │ ├── podcast-index/
70
+ │ │ ├── auth.ts # HMAC-SHA1 auth headers (server-only, uses Node crypto)
71
+ │ │ ├── client.ts # Typed PodcastIndexClient
72
+ │ │ └── index.ts # Barrel export
73
+ │ ├── styles/
74
+ │ │ └── podcast-player.css # Plain CSS with custom property theming (pw- prefix)
75
+ │ └── index.ts # Main barrel export
76
+ ├── package.json # Dual ESM/CJS, subpath exports
77
+ ├── tsconfig.json # Client-side TS config
78
+ ├── tsconfig.server.json # Server-side (podcast-index) config
79
+ └── tsup.config.ts # Build config
80
+ ```
81
+
82
+ ## Player Modes
83
+
84
+ The package provides two player modes that can be used independently or together. Each mode accepts a `controls` config to toggle which controls are visible.
85
+
86
+ ### Controls Config
87
+
88
+ All controls default to `false` (opt-in):
89
+
90
+ ```typescript
91
+ interface ControlsConfig {
92
+ playPause?: boolean;
93
+ skipForward?: boolean;
94
+ skipBackward?: boolean;
95
+ volume?: boolean;
96
+ speed?: boolean;
97
+ progress?: boolean;
98
+ playlist?: boolean; // Inline dropdown playlist (mini) or full playlist (full)
99
+ expand?: boolean; // Button to emit 'expand' event
100
+ }
101
+ ```
102
+
103
+ ### MiniPlayer
104
+
105
+ Compact horizontal bar. Defaults: `playPause: true, progress: true`.
106
+
107
+ ```typescript
108
+ const mini = new MiniPlayer({
109
+ container: document.getElementById('mini-player')!,
110
+ controller,
111
+ controls: {
112
+ playPause: true,
113
+ progress: true,
114
+ volume: true,
115
+ playlist: true, // Adds inline dropdown playlist
116
+ expand: true, // Adds expand button
117
+ },
118
+ });
119
+
120
+ mini.on('expand', () => { /* open full player, etc. */ });
121
+ mini.destroy(); // Cleanup when done
122
+ ```
123
+
124
+ ### FullPlayer
125
+
126
+ Modal overlay with hero section (blurred artwork background), controls, and scrollable playlist. Defaults: all controls enabled.
127
+
128
+ ```typescript
129
+ const full = new FullPlayer({
130
+ container: document.getElementById('full-player')!,
131
+ backdrop: document.getElementById('backdrop'), // Optional separate backdrop element
132
+ controller,
133
+ });
134
+
135
+ full.show(); // Open modal
136
+ full.hide(); // Close modal
137
+ full.on('close', () => { /* cleanup, etc. */ });
138
+ full.destroy();
139
+ ```
140
+
141
+ **Keyboard shortcuts** (when full player is visible):
142
+ - `Space` / `k` — play/pause
143
+ - `ArrowLeft` — skip backward
144
+ - `ArrowRight` — skip forward
145
+ - `Escape` — close
146
+
147
+ ## Core API
148
+
149
+ ### AudioEngine
150
+
151
+ Wraps `HTMLAudioElement` with typed events and proper cleanup.
152
+
153
+ ```typescript
154
+ const engine = new AudioEngine(30); // skip seconds (default: 30)
155
+
156
+ engine.load(url, startPosition?);
157
+ await engine.play();
158
+ engine.pause();
159
+ engine.stop();
160
+ engine.skipForward();
161
+ engine.skipBackward();
162
+ engine.seek(120); // Seek to 120 seconds
163
+ engine.seekToPercentage(50); // Seek to 50%
164
+
165
+ engine.volume = 0.8;
166
+ engine.playbackRate = 1.5;
167
+
168
+ engine.on('play', () => {});
169
+ engine.on('pause', ({ currentTime }) => {});
170
+ engine.on('time-update', ({ currentTime, duration, percentage }) => {});
171
+ engine.on('ended', () => {});
172
+ engine.on('error', ({ error, context }) => {});
173
+
174
+ engine.destroy(); // Removes all listeners, releases audio element
175
+ ```
176
+
177
+ ### PlayerController
178
+
179
+ Orchestrates AudioEngine, PlaybackStorage, and EpisodeProvider. Manages episode state, resume positions, and player preferences.
180
+
181
+ ```typescript
182
+ const controller = new PlayerController(engine, provider, {
183
+ storagePrefix: 'podcast', // localStorage key prefix (default: "podcast")
184
+ maxStoredPositions: 100, // Max saved resume positions (default: 100)
185
+ positionSaveInterval: 5000, // Save interval in ms (default: 5000)
186
+ skipSeconds: 30, // Skip amount (default: 30)
187
+ episodeCacheTTL: 3600000, // Cache TTL in ms (default: 1 hour)
188
+ });
189
+
190
+ await controller.loadEpisodes();
191
+ controller.loadEpisode(0); // Load without playing
192
+ controller.playEpisode(2); // Load and play
193
+ controller.setSpeed(1.5);
194
+ controller.setVolume(0.8);
195
+
196
+ controller.on('episode-change', ({ episode, index }) => {});
197
+ controller.on('episodes-loaded', ({ episodes }) => {});
198
+ controller.on('episode-display', ({ imageUrl, title, show }) => {});
199
+
200
+ controller.destroy();
201
+ ```
202
+
203
+ ### EpisodeProvider
204
+
205
+ Interface for loading episodes. The package ships `FetchEpisodeProvider` which fetches from a URL with caching and retry.
206
+
207
+ ```typescript
208
+ // Use the built-in fetch provider
209
+ const provider = new FetchEpisodeProvider('/api/episodes', resolvedConfig);
210
+
211
+ // Or implement your own
212
+ const customProvider: EpisodeProvider = {
213
+ async getEpisodes() {
214
+ return [
215
+ { id: '1', feedId: 123, feedName: 'My Show', title: 'Ep 1', audioUrl: '...', pubDate: '...' },
216
+ ];
217
+ },
218
+ };
219
+ ```
220
+
221
+ The `FetchEpisodeProvider` expects the endpoint to return `{ episodes: Episode[] }`.
222
+
223
+ ### Episode Interface
224
+
225
+ ```typescript
226
+ interface Episode {
227
+ id: string;
228
+ feedId: number;
229
+ feedName: string;
230
+ title: string;
231
+ audioUrl: string;
232
+ pubDate: string;
233
+ pubDateTime?: string;
234
+ pubTimestamp?: number;
235
+ duration?: number;
236
+ image?: string;
237
+ feedImage?: string;
238
+ artwork?: string;
239
+ }
240
+ ```
241
+
242
+ ## CSS Theming
243
+
244
+ Import the styles:
245
+
246
+ ```typescript
247
+ import 'podcast-widget/styles';
248
+ ```
249
+
250
+ Or link directly:
251
+
252
+ ```html
253
+ <link rel="stylesheet" href="node_modules/podcast-widget/dist/podcast-player.css">
254
+ ```
255
+
256
+ Define these CSS custom properties on a parent element to theme the player:
257
+
258
+ ```css
259
+ .my-player-wrapper {
260
+ --player-surface: #002b36; /* Player background */
261
+ --player-surface-variant: #073642; /* Secondary background */
262
+ --player-on-surface: #839496; /* Primary text */
263
+ --player-on-surface-variant: #657b83; /* Secondary text */
264
+ --player-on-surface-rgb: 131, 148, 150; /* RGB triplet for rgba() overlays */
265
+ --player-outline: #586e75; /* Borders */
266
+ --player-outline-variant: #073642; /* Subtle borders */
267
+ --md-primary: #268bd2; /* Accent (play button, active episode) */
268
+ --md-on-primary: #fdf6e3; /* Text on accent */
269
+ --md-secondary: #2aa198; /* Secondary accent (saved position) */
270
+ --md-on-secondary: #fdf6e3; /* Text on secondary accent */
271
+ }
272
+ ```
273
+
274
+ All CSS classes use the `pw-` prefix to avoid collisions.
275
+
276
+ ## PodcastIndex Client (Server-Only)
277
+
278
+ Separate subpath export for server-side use. Uses Node's `crypto` module for HMAC-SHA1 auth — not included in the browser bundle.
279
+
280
+ ```typescript
281
+ import { PodcastIndexClient } from 'podcast-widget/podcast-index';
282
+
283
+ const client = new PodcastIndexClient(API_KEY, API_SECRET);
284
+
285
+ const episodes = await client.getEpisodes(feedId, 10);
286
+ const latest = await client.getLatestEpisode(feedId);
287
+ const feed = await client.getFeedInfo(feedId);
288
+ const results = await client.search('javascript');
289
+ ```
290
+
291
+ You can also use the auth headers directly:
292
+
293
+ ```typescript
294
+ import { createPodcastIndexHeaders } from 'podcast-widget/podcast-index';
295
+
296
+ const headers = createPodcastIndexHeaders(apiKey, apiSecret);
297
+ // { 'X-Auth-Key': '...', 'X-Auth-Date': '...', Authorization: '...', 'User-Agent': '...' }
298
+ ```
299
+
300
+ ## Local Development
301
+
302
+ ```bash
303
+ npm run build # Build
304
+ npm run dev # Build + watch
305
+ npm run typecheck # Type check
306
+ npm test # Run tests
307
+ ```
308
+
309
+ ### Testing in a Consumer Before Publishing
310
+
311
+ ```bash
312
+ cd /path/to/podcast-widget
313
+ npm run build
314
+ npm link
315
+
316
+ cd /path/to/my-site
317
+ npm link podcast-widget
318
+ ```
319
+
320
+ Now `import ... from 'podcast-widget'` resolves to your local build. Run `npm run build` in podcast-widget after changes and the consumer picks them up immediately.
321
+
322
+ When done:
323
+
324
+ ```bash
325
+ cd /path/to/my-site
326
+ npm unlink podcast-widget
327
+ npm install
328
+ ```
329
+
330
+ ## Publishing
331
+
332
+ ```bash
333
+ npm login # First time only
334
+ npm publish
335
+ ```
336
+
337
+ Version bumping:
338
+
339
+ ```bash
340
+ npm version patch # 0.1.0 → 0.1.1 (bug fixes)
341
+ npm version minor # 0.1.1 → 0.2.0 (new features)
342
+ npm version major # 0.2.0 → 1.0.0 (breaking changes)
343
+ ```
344
+
345
+ ## License
346
+
347
+ MIT