@scribeberry/sdk 0.2.0 → 0.3.0

package/README.md

@@ -263,6 +263,66 @@ const result = await session.stop(); // Stop and get final result
 
 ---
 
+## React Hooks
+
+The SDK includes optional React bindings via `@scribeberry/sdk/react`. These
+handle microphone access, audio processing, and WebSocket streaming with a
+simple hook interface.
+
+> **Peer dependency:** Requires `react >= 18`.
+
+### `useTranscription(options)`
+
+```tsx
+import { useTranscription } from '@scribeberry/sdk/react';
+
+function Recorder() {
+  const {
+    status,     // 'idle' | 'connecting' | 'recording' | 'error'
+    transcript, // Full confirmed transcript string
+    partial,    // Interim text (updates rapidly, not yet confirmed)
+    segments,   // All confirmed TranscriptSegment objects
+    error,      // Error message or null
+    durationSeconds, // Session duration (available after stop)
+    start,      // Start recording from microphone
+    stop,       // Stop recording
+    clear,      // Clear transcript and reset to idle
+  } = useTranscription({
+    getRealtimeToken: async () => {
+      const res = await fetch('/api/realtime-token', { method: 'POST' });
+      return res.json(); // { token, expiresAt }
+    },
+    language: 'en-US',           // optional, default: 'en-US'
+    enableDiarization: true,     // optional, default: true
+  });
+
+  return (
+    <div>
+      <button onClick={status === 'recording' ? stop : start}>
+        {status === 'recording' ? '⏹ Stop' : '🎙 Record'}
+      </button>
+      <p>
+        {transcript}
+        <span style={{ opacity: 0.5 }}>{partial}</span>
+      </p>
+      {transcript && <button onClick={clear}>Clear</button>}
+    </div>
+  );
+}
+```
+
+| Option              | Type       | Required | Description                                                  |
+| ------------------- | ---------- | -------- | ------------------------------------------------------------ |
+| `getRealtimeToken`  | `function` | ✅       | Async callback returning `{ token, expiresAt }` from your server |
+| `language`          | `string`   |          | Language code (default: `en-US`)                             |
+| `enableDiarization` | `boolean`  |          | Speaker identification (default: `true`)                     |
+
+The hook manages the full lifecycle: microphone permissions → AudioWorklet
+processing → WebSocket streaming → React state updates. Your API key never
+leaves the server — only short-lived `sb_rt_*` tokens are used in the browser.
+
+---
+
 ## Audio Format Requirements
 
 For realtime transcription, audio must be:

package/dist/index.js

@@ -28,15 +28,15 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var index_exports = {};
-__export(index_exports, {
+var src_exports = {};
+__export(src_exports, {
   AuthenticationError: () => AuthenticationError,
   RateLimitError: () => RateLimitError,
   RealtimeTranscriptionSession: () => RealtimeTranscriptionSession,
   Scribeberry: () => Scribeberry,
   ScribeberryError: () => ScribeberryError
 });
-module.exports = __toCommonJS(index_exports);
+module.exports = __toCommonJS(src_exports);
 
 // src/lib/errors.ts
 var ScribeberryError = class extends Error {

package/dist/react.d.mts

@@ -0,0 +1,120 @@
+/**
+ * A confirmed transcript segment from the realtime stream.
+ */
+interface TranscriptSegment {
+    /** Confirmed text content. */
+    text: string;
+    /** Speaker identifier (if diarization is enabled). */
+    speaker?: number;
+    /** Segment start time in milliseconds from session start. */
+    startMs: number;
+    /** Segment end time in milliseconds from session start. */
+    endMs: number;
+}
+
+/**
+ * Result from a `getRealtimeToken` callback.
+ */
+interface RealtimeTokenResult {
+    /** Temporary token prefixed with `sb_rt_`. */
+    token: string;
+    /** ISO 8601 expiration timestamp. */
+    expiresAt: string;
+}
+
+/** Status of the transcription session. */
+type TranscriptionStatus = 'idle' | 'connecting' | 'recording' | 'error';
+/** Configuration for `useTranscription`. */
+interface UseTranscriptionOptions {
+    /**
+     * Async callback that returns a temporary realtime token from your server.
+     *
+     * This is called each time `start()` is invoked. Your server should call
+     * `sb.realtime.createToken()` with a full API key and return the result.
+     *
+     * @example
+     * ```tsx
+     * useTranscription({
+     *   getRealtimeToken: async () => {
+     *     const res = await fetch('/api/realtime-token', { method: 'POST' });
+     *     return res.json(); // { token, expiresAt }
+     *   },
+     * });
+     * ```
+     */
+    getRealtimeToken: () => Promise<RealtimeTokenResult>;
+    /** Source language for transcription. Default: `'en-US'`. */
+    language?: string;
+    /** Enable speaker diarization. Default: `true`. */
+    enableDiarization?: boolean;
+}
+/** State returned by the `useTranscription` hook. */
+interface TranscriptionState {
+    /** Current lifecycle status. */
+    status: TranscriptionStatus;
+    /** All confirmed transcript segments (stable text). */
+    segments: TranscriptSegment[];
+    /** Interim text that updates rapidly as words are recognized. */
+    partial: string;
+    /** Full confirmed transcript as a single string. */
+    transcript: string;
+    /** Session duration in seconds (available after stop). */
+    durationSeconds: number | null;
+    /** Error message if something went wrong, otherwise `null`. */
+    error: string | null;
+}
+/** Actions returned by the `useTranscription` hook. */
+interface TranscriptionActions {
+    /** Request microphone access and start transcribing. */
+    start: () => Promise<void>;
+    /** Stop the session and release the microphone. */
+    stop: () => Promise<void>;
+    /** Clear all state and return to idle. */
+    clear: () => void;
+}
+/**
+ * React hook for realtime medical transcription.
+ *
+ * Manages the full lifecycle: microphone access → AudioWorklet processing →
+ * WebSocket streaming → transcript state. Your API key never leaves the
+ * server — the hook uses a token callback to obtain short-lived credentials.
+ *
+ * @param options - Configuration including the required `getRealtimeToken` callback.
+ * @returns Transcription state and actions (`start`, `stop`, `clear`).
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useTranscription } from '@scribeberry/sdk/react';
+ *
+ * function Recorder() {
+ *   const { status, transcript, partial, start, stop, clear } = useTranscription({
+ *     getRealtimeToken: async () => {
+ *       const res = await fetch('/api/realtime-token', { method: 'POST' });
+ *       return res.json();
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={status === 'recording' ? stop : start}>
+ *         {status === 'recording' ? 'Stop' : 'Record'}
+ *       </button>
+ *       <p>{transcript}<span style={{ opacity: 0.5 }}>{partial}</span></p>
+ *       {transcript && <button onClick={clear}>Clear</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With language and diarization options
+ * ```tsx
+ * const transcription = useTranscription({
+ *   getRealtimeToken: fetchToken,
+ *   language: 'fr-FR',
+ *   enableDiarization: false,
+ * });
+ * ```
+ */
+declare function useTranscription(options: UseTranscriptionOptions): TranscriptionState & TranscriptionActions;
+
+export { type TranscriptionActions, type TranscriptionState, type TranscriptionStatus, type UseTranscriptionOptions, useTranscription };

package/dist/react.d.ts

@@ -0,0 +1,120 @@
+/**
+ * A confirmed transcript segment from the realtime stream.
+ */
+interface TranscriptSegment {
+    /** Confirmed text content. */
+    text: string;
+    /** Speaker identifier (if diarization is enabled). */
+    speaker?: number;
+    /** Segment start time in milliseconds from session start. */
+    startMs: number;
+    /** Segment end time in milliseconds from session start. */
+    endMs: number;
+}
+
+/**
+ * Result from a `getRealtimeToken` callback.
+ */
+interface RealtimeTokenResult {
+    /** Temporary token prefixed with `sb_rt_`. */
+    token: string;
+    /** ISO 8601 expiration timestamp. */
+    expiresAt: string;
+}
+
+/** Status of the transcription session. */
+type TranscriptionStatus = 'idle' | 'connecting' | 'recording' | 'error';
+/** Configuration for `useTranscription`. */
+interface UseTranscriptionOptions {
+    /**
+     * Async callback that returns a temporary realtime token from your server.
+     *
+     * This is called each time `start()` is invoked. Your server should call
+     * `sb.realtime.createToken()` with a full API key and return the result.
+     *
+     * @example
+     * ```tsx
+     * useTranscription({
+     *   getRealtimeToken: async () => {
+     *     const res = await fetch('/api/realtime-token', { method: 'POST' });
+     *     return res.json(); // { token, expiresAt }
+     *   },
+     * });
+     * ```
+     */
+    getRealtimeToken: () => Promise<RealtimeTokenResult>;
+    /** Source language for transcription. Default: `'en-US'`. */
+    language?: string;
+    /** Enable speaker diarization. Default: `true`. */
+    enableDiarization?: boolean;
+}
+/** State returned by the `useTranscription` hook. */
+interface TranscriptionState {
+    /** Current lifecycle status. */
+    status: TranscriptionStatus;
+    /** All confirmed transcript segments (stable text). */
+    segments: TranscriptSegment[];
+    /** Interim text that updates rapidly as words are recognized. */
+    partial: string;
+    /** Full confirmed transcript as a single string. */
+    transcript: string;
+    /** Session duration in seconds (available after stop). */
+    durationSeconds: number | null;
+    /** Error message if something went wrong, otherwise `null`. */
+    error: string | null;
+}
+/** Actions returned by the `useTranscription` hook. */
+interface TranscriptionActions {
+    /** Request microphone access and start transcribing. */
+    start: () => Promise<void>;
+    /** Stop the session and release the microphone. */
+    stop: () => Promise<void>;
+    /** Clear all state and return to idle. */
+    clear: () => void;
+}
+/**
+ * React hook for realtime medical transcription.
+ *
+ * Manages the full lifecycle: microphone access → AudioWorklet processing →
+ * WebSocket streaming → transcript state. Your API key never leaves the
+ * server — the hook uses a token callback to obtain short-lived credentials.
+ *
+ * @param options - Configuration including the required `getRealtimeToken` callback.
+ * @returns Transcription state and actions (`start`, `stop`, `clear`).
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useTranscription } from '@scribeberry/sdk/react';
+ *
+ * function Recorder() {
+ *   const { status, transcript, partial, start, stop, clear } = useTranscription({
+ *     getRealtimeToken: async () => {
+ *       const res = await fetch('/api/realtime-token', { method: 'POST' });
+ *       return res.json();
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={status === 'recording' ? stop : start}>
+ *         {status === 'recording' ? 'Stop' : 'Record'}
+ *       </button>
+ *       <p>{transcript}<span style={{ opacity: 0.5 }}>{partial}</span></p>
+ *       {transcript && <button onClick={clear}>Clear</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With language and diarization options
+ * ```tsx
+ * const transcription = useTranscription({
+ *   getRealtimeToken: fetchToken,
+ *   language: 'fr-FR',
+ *   enableDiarization: false,
+ * });
+ * ```
+ */
+declare function useTranscription(options: UseTranscriptionOptions): TranscriptionState & TranscriptionActions;
+
+export { type TranscriptionActions, type TranscriptionState, type TranscriptionStatus, type UseTranscriptionOptions, useTranscription };