@scribeberry/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,707 @@
+/**
+ * Error classes for the Scribeberry SDK.
+ */
+/**
+ * Base error thrown by the Scribeberry SDK.
+ * All SDK errors extend this class.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sb.templates.list();
+ * } catch (error) {
+ *   if (error instanceof ScribeberryError) {
+ *     console.error(`[${error.code}] ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+declare class ScribeberryError extends Error {
+    /** Machine-readable error code. */
+    readonly code: string;
+    /** HTTP status code (if applicable). */
+    readonly status?: number | undefined;
+    constructor(message: string, 
+    /** Machine-readable error code. */
+    code: string, 
+    /** HTTP status code (if applicable). */
+    status?: number | undefined);
+}
+/**
+ * Thrown when authentication fails (invalid or expired API key / token).
+ */
+declare class AuthenticationError extends ScribeberryError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the rate limit is exceeded.
+ */
+declare class RateLimitError extends ScribeberryError {
+    constructor(message?: string);
+}
+
+/**
+ * Result from a `getRealtimeToken` callback.
+ */
+interface RealtimeTokenResult {
+    /** Temporary token prefixed with `sb_rt_`. */
+    token: string;
+    /** ISO 8601 expiration timestamp. */
+    expiresAt: string;
+}
+/**
+ * Configuration for the Scribeberry SDK.
+ *
+ * @example Server-side (full API key)
+ * ```typescript
+ * const sb = new Scribeberry({ apiKey: 'sk_live_...' });
+ * ```
+ *
+ * @example Browser with token callback (recommended)
+ * ```typescript
+ * const sb = new Scribeberry({
+ *   baseUrl: 'https://sandbox.api.scribeberry.com',
+ *   getRealtimeToken: async () => {
+ *     const res = await fetch('/api/realtime-token', { method: 'POST' });
+ *     return res.json(); // { token: 'sb_rt_...', expiresAt: '...' }
+ *   },
+ * });
+ * ```
+ *
+ * @example Browser with static token (manual refresh)
+ * ```typescript
+ * const sb = new Scribeberry({ apiKey: 'sb_rt_...' });
+ * ```
+ */
+interface ScribeberryConfig {
+    /**
+     * Your API key or temporary realtime token.
+     *
+     * - `sk_test_*` / `sk_live_*` — Full API key (server-side only).
+     * - `sb_rt_*` — Temporary realtime token (safe for browser use).
+     *
+     * **Not required** if `getRealtimeToken` is provided.
+     */
+    apiKey?: string;
+    /**
+     * Async callback that fetches a temporary realtime token from your server.
+     *
+     * This is the **recommended pattern for browser-side realtime transcription**.
+     * The SDK calls this function when it needs a token (on connect and before expiry),
+     * so you never have to manage token lifecycle manually.
+     *
+     * @example
+     * ```typescript
+     * const sb = new Scribeberry({
+     *   getRealtimeToken: async () => {
+     *     const res = await fetch('/api/realtime-token', {
+     *       method: 'POST',
+     *       headers: { Authorization: `Bearer ${myUserJwt}` },
+     *     });
+     *     return res.json(); // { token: 'sb_rt_...', expiresAt: '...' }
+     *   },
+     * });
+     * ```
+     */
+    getRealtimeToken?: () => Promise<RealtimeTokenResult>;
+    /**
+     * API base URL. Defaults to `https://api.scribeberry.com`.
+     *
+     * Use `https://sandbox.api.scribeberry.com` for development/testing.
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds. Default: 30000 (30 seconds).
+     */
+    timeout?: number;
+}
+/**
+ * Paginated API response.
+ */
+interface PaginatedResponse<T> {
+    items: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        totalPages: number;
+        totalCount: number;
+    };
+}
+
+/**
+ * Low-level HTTP client for the Scribeberry API.
+ * Handles authentication, error mapping, and request/response serialization.
+ *
+ * @internal Used by resource classes. Not intended for direct use.
+ */
+declare class HttpClient {
+    readonly apiKey: string | undefined;
+    readonly baseUrl: string;
+    readonly timeout: number;
+    /** True if the API key is a temporary realtime token (sb_rt_*). */
+    readonly isTemporaryToken: boolean;
+    /** True if a getRealtimeToken callback was provided (browser token-provider mode). */
+    readonly hasTokenProvider: boolean;
+    /** The token provider callback (if any). */
+    private readonly getRealtimeToken?;
+    /** Current realtime token (fetched via callback or static). */
+    private currentToken;
+    /** When the current token expires. */
+    private tokenExpiresAt;
+    /** Active refresh timer. */
+    private refreshTimer;
+    /** Listeners notified on token refresh. */
+    private tokenRefreshListeners;
+    constructor(config: ScribeberryConfig);
+    /**
+     * The WebSocket URL derived from the base URL.
+     */
+    get wsUrl(): string;
+    /**
+     * Get the current realtime token for WebSocket connections.
+     * If a getRealtimeToken callback is configured, fetches/refreshes as needed.
+     * Otherwise returns the static apiKey.
+     */
+    getWsToken(): Promise<string>;
+    /**
+     * Fetch a fresh token from the callback and schedule auto-refresh.
+     */
+    refreshToken(): Promise<string>;
+    /**
+     * Register a listener that's called when the token is refreshed.
+     * Used by RealtimeTranscriptionSession to reconnect with the new token.
+     */
+    onTokenRefresh(listener: (token: string) => void): void;
+    /**
+     * Remove a token refresh listener.
+     */
+    offTokenRefresh(listener: (token: string) => void): void;
+    /**
+     * Schedule an automatic token refresh before the current token expires.
+     */
+    private scheduleRefresh;
+    /**
+     * Make an authenticated HTTP request to the Scribeberry API.
+     */
+    request<T>(method: string, path: string, options?: {
+        body?: any;
+        params?: Record<string, string | number | boolean | undefined>;
+        timeout?: number;
+    }): Promise<T>;
+    private getFetch;
+    private handleError;
+}
+
+/**
+ * A note template defining the output structure.
+ */
+interface Template {
+    id: string;
+    name: string;
+    description: string;
+    documentType: string;
+    headings: string[];
+    categories: string[];
+    isPublic: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Options for creating a new template.
+ */
+interface CreateTemplateOptions {
+    name: string;
+    description?: string;
+    content: string;
+    documentType: string;
+    headings?: string[];
+    categories?: string[];
+}
+/**
+ * Options for listing templates.
+ */
+interface ListTemplatesOptions {
+    page?: number;
+    pageSize?: number;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+
+/**
+ * Manage note templates.
+ *
+ * @example
+ * ```typescript
+ * const templates = await sb.templates.list();
+ * const template = await sb.templates.get('template-id');
+ * ```
+ */
+declare class Templates {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all templates (paginated).
+     */
+    list(options?: ListTemplatesOptions): Promise<PaginatedResponse<Template>>;
+    /**
+     * Get a template by ID.
+     */
+    get(templateId: string): Promise<Template>;
+    /**
+     * Create a new template.
+     */
+    create(options: CreateTemplateOptions): Promise<Template>;
+    /**
+     * Delete a template.
+     */
+    delete(templateId: string): Promise<void>;
+}
+
+/**
+ * Options for generating a note.
+ *
+ * Provide either `conversationText` or `audioUrl` (or both).
+ */
+interface GenerateNoteOptions {
+    /** Template ID to use for note generation. */
+    templateId: string;
+    /** Conversation text to generate the note from. */
+    conversationText?: string;
+    /** URL of an audio file to transcribe and generate a note from. */
+    audioUrl?: string;
+    /** Source language for transcription. Default: 'en-US'. */
+    sourceLanguage?: string;
+    /** Transcription quality. Default: 'high'. */
+    transcriptionQuality?: 'low' | 'medium' | 'high';
+    /** Additional context for the note generation. */
+    context?: Record<string, string>;
+}
+/**
+ * A generated note.
+ */
+interface Note {
+    /** Note content in Markdown format. */
+    markdown: string;
+    /** Note content as plain text. */
+    text: string;
+    /** Structured note sections (key = heading, value = content). */
+    structured: Record<string, string>;
+}
+/**
+ * Result of a note generation request.
+ */
+interface GenerateNoteResult {
+    /** The generated note. */
+    note: Note;
+    /** Transcript data (if audio was provided). */
+    transcript?: {
+        text: string;
+        confidence: number;
+        duration: number;
+        sourceLanguage: string;
+    };
+    /** Template that was used. */
+    template: {
+        id: string;
+        name: string;
+    };
+}
+
+/**
+ * Generate structured medical notes from text or audio.
+ *
+ * @example
+ * ```typescript
+ * // From text
+ * const result = await sb.notes.generate({
+ *   templateId: 'template-id',
+ *   conversationText: 'Patient presents with...',
+ * });
+ *
+ * // From audio URL
+ * const result = await sb.notes.generate({
+ *   templateId: 'template-id',
+ *   audioUrl: 'https://example.com/recording.wav',
+ * });
+ * ```
+ */
+declare class Notes {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Generate a note from conversation text or audio.
+     *
+     * @param options - Note generation options.
+     * @returns The generated note with optional transcript data.
+     */
+    generate(options: GenerateNoteOptions): Promise<GenerateNoteResult>;
+}
+
+/**
+ * Configuration for a realtime transcription session.
+ */
+interface RealtimeConfig {
+    /** Source language. Default: `'en-US'`. */
+    language?: string;
+    /** Enable speaker diarization. Default: `true`. */
+    enableDiarization?: boolean;
+    /**
+     * Template ID for automatic note generation when the session stops.
+     * If provided, the server generates a note from the accumulated transcript
+     * and pushes it back via the `'note'` event.
+     */
+    templateId?: string;
+}
+/**
+ * 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 returned when a realtime session is stopped.
+ */
+interface RealtimeSessionResult {
+    /** Full accumulated transcript text. */
+    transcript: string;
+    /** Individual confirmed transcript segments. */
+    segments: TranscriptSegment[];
+    /** Session duration in seconds. */
+    durationSeconds: number;
+    /** Generated note (if `templateId` was provided). */
+    note?: Note;
+}
+/**
+ * Events emitted by a `RealtimeTranscriptionSession`.
+ */
+interface RealtimeSessionEvents {
+    /**
+     * Partial (interim) transcript — updates in real-time as words
+     * are recognized. Each partial replaces the previous one.
+     */
+    partial: (text: string, speaker?: number) => void;
+    /**
+     * Final confirmed transcript segment. This text is stable and won't change.
+     * Accumulate these segments to build the full transcript.
+     */
+    final: (segment: TranscriptSegment) => void;
+    /**
+     * Natural speech endpoint detected (pause between utterances).
+     */
+    endpoint: () => void;
+    /**
+     * Note generated from the accumulated transcript (requires `templateId`).
+     */
+    note: (note: Note) => void;
+    /**
+     * Session started and ready to receive audio.
+     */
+    started: (sessionId: string) => void;
+    /**
+     * Session stopped. Contains final transcript and usage info.
+     */
+    stopped: (result: RealtimeSessionResult) => void;
+    /**
+     * An error occurred during the session.
+     */
+    error: (error: Error) => void;
+}
+/**
+ * Options for creating a temporary realtime token.
+ */
+interface CreateRealtimeTokenOptions {
+    /**
+     * Token lifetime in seconds. Default: 3600 (1 hour). Maximum: 3600.
+     */
+    expiresInSeconds?: number;
+}
+/**
+ * A temporary realtime token for browser-side WebSocket access.
+ */
+interface RealtimeToken {
+    /** Temporary token prefixed with `sb_rt_`. */
+    token: string;
+    /** ISO 8601 expiration timestamp. */
+    expiresAt: string;
+    /** WebSocket URL to connect to for realtime transcription. */
+    wsUrl: string;
+}
+
+/**
+ * A realtime transcription session over WebSocket.
+ *
+ * Audio is streamed to the Scribeberry server and transcript events are
+ * emitted as speech is recognized. The session accumulates confirmed
+ * segments so you can retrieve the full transcript at any time.
+ *
+ * **Audio format:** PCM 16-bit signed little-endian, 16kHz, mono.
+ *
+ * @example
+ * ```typescript
+ * const session = sb.realtime.transcribe({
+ *   language: 'en-US',
+ *   templateId: 'template-id', // auto-generate note on stop
+ * });
+ *
+ * session.on('partial', (text) => console.log('Interim:', text));
+ * session.on('final', (segment) => console.log('Confirmed:', segment.text));
+ * session.on('stopped', (result) => console.log('Full:', result.transcript));
+ *
+ * // Stream audio chunks
+ * session.sendAudio(audioBuffer);
+ *
+ * // When done
+ * const result = await session.stop();
+ * console.log(result.transcript);
+ * ```
+ */
+declare class RealtimeTranscriptionSession {
+    private readonly http;
+    private readonly config;
+    private ws;
+    private _sessionId;
+    private _state;
+    private segments;
+    private durationSeconds;
+    private note;
+    private stopResolver;
+    private handlers;
+    constructor(http: HttpClient, config: RealtimeConfig);
+    /** Current session state. */
+    get state(): "idle" | "connecting" | "active" | "stopping" | "stopped";
+    /** Session ID (available after `'started'` event). */
+    get sessionId(): string | null;
+    /**
+     * Get the full accumulated transcript text at any point during the session.
+     *
+     * @returns Concatenated text from all confirmed segments.
+     */
+    getTranscript(): string;
+    /**
+     * Get all confirmed transcript segments.
+     *
+     * @returns A copy of the segments array.
+     */
+    getSegments(): TranscriptSegment[];
+    /**
+     * Connect to the realtime transcription server.
+     *
+     * Called automatically by `sb.realtime.transcribe()`. You don't usually
+     * need to call this directly.
+     *
+     * @throws {ScribeberryError} If the session has already been started
+     */
+    connect(): Promise<void>;
+    /**
+     * Send an audio chunk to the server for transcription.
+     *
+     * **Required format:** PCM 16-bit signed little-endian, 16kHz, mono.
+     *
+     * @param data - Raw audio data
+     * @throws {ScribeberryError} If the session is not active
+     */
+    sendAudio(data: ArrayBuffer | Uint8Array | Buffer): void;
+    /**
+     * Stream audio from an async iterable source (e.g., microphone stream).
+     *
+     * @param stream - Async iterable of audio chunks.
+     */
+    sendStream(stream: AsyncIterable<ArrayBuffer | Uint8Array | Buffer>): Promise<void>;
+    /**
+     * Pause audio streaming. The WebSocket connection stays alive.
+     */
+    pause(): void;
+    /**
+     * Resume audio streaming after a pause.
+     */
+    resume(): void;
+    /**
+     * Request finalization of the current audio buffer.
+     * Forces the server to emit any pending partial results as final.
+     */
+    finalize(): void;
+    /**
+     * Stop the session gracefully.
+     *
+     * Waits for the server to confirm the stop and (if configured) for
+     * note generation to complete.
+     *
+     * @returns Final transcript, segments, duration, and optional note.
+     */
+    stop(): Promise<RealtimeSessionResult>;
+    /**
+     * Register an event handler.
+     *
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * session
+     *   .on('partial', (text) => console.log('Interim:', text))
+     *   .on('final', (segment) => console.log('Confirmed:', segment.text))
+     *   .on('error', (err) => console.error(err));
+     * ```
+     */
+    on<E extends keyof RealtimeSessionEvents>(event: E, handler: RealtimeSessionEvents[E]): this;
+    /**
+     * Remove an event handler.
+     *
+     * @param event - Event name
+     * @param handler - Handler to remove
+     * @returns `this` for chaining
+     */
+    off<E extends keyof RealtimeSessionEvents>(event: E, handler: RealtimeSessionEvents[E]): this;
+    private emit;
+    private send;
+    private handleMessage;
+    private resolveStop;
+    private buildResult;
+    private cleanup;
+}
+
+/**
+ * Realtime transcription API.
+ *
+ * @example Server-side: create a temporary token for browser clients
+ * ```typescript
+ * const sb = new Scribeberry({ apiKey: 'sk_live_...' });
+ * const { token, wsUrl } = await sb.realtime.createToken();
+ * // Send token + wsUrl to the browser
+ * ```
+ *
+ * @example Browser: use a temporary token for realtime transcription
+ * ```typescript
+ * const sb = new Scribeberry({ apiKey: 'sb_rt_...' });
+ * const session = sb.realtime.transcribe({ language: 'en-US' });
+ *
+ * session.on('partial', (text) => updateUI(text));
+ * session.on('final', (segment) => appendTranscript(segment));
+ *
+ * session.sendAudio(audioChunk);
+ *
+ * const result = await session.stop();
+ * ```
+ */
+declare class Realtime {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a temporary realtime token for browser-side WebSocket access.
+     *
+     * **Server-side only.** Call this from your backend, then pass the token
+     * to your frontend for use with `new Scribeberry({ apiKey: token })`.
+     *
+     * @param options - Token creation options.
+     * @returns A temporary token and the WebSocket URL.
+     *
+     * @example
+     * ```typescript
+     * // On your server
+     * const sb = new Scribeberry({ apiKey: 'sk_live_...' });
+     * const { token, wsUrl, expiresAt } = await sb.realtime.createToken({
+     *   expiresInSeconds: 3600,
+     * });
+     *
+     * // Return token to the browser client
+     * res.json({ token, wsUrl, expiresAt });
+     * ```
+     *
+     * @throws {ScribeberryError} If called in a browser environment
+     * @throws {ScribeberryError} If called with a temporary token (sb_rt_*)
+     */
+    createToken(options?: CreateRealtimeTokenOptions): Promise<RealtimeToken>;
+    /**
+     * Start a new realtime transcription session.
+     *
+     * The session connects via WebSocket and streams transcription results
+     * back as audio is sent. Optionally generates a note when stopped.
+     *
+     * **Audio format:** PCM 16-bit signed little-endian, 16kHz, mono.
+     *
+     * @param config - Session configuration.
+     * @returns A realtime transcription session.
+     *
+     * @example
+     * ```typescript
+     * const session = sb.realtime.transcribe({
+     *   language: 'en-US',
+     *   enableDiarization: true,
+     *   templateId: 'template-id',
+     * });
+     *
+     * session.on('partial', (text) => console.log('Partial:', text));
+     * session.on('final', (segment) => console.log('Final:', segment.text));
+     * session.on('stopped', (result) => console.log('Transcript:', result.transcript));
+     *
+     * // Stream audio chunks from your microphone
+     * session.sendAudio(audioChunk);
+     *
+     * // When done
+     * const result = await session.stop();
+     * ```
+     */
+    transcribe(config?: RealtimeConfig): RealtimeTranscriptionSession;
+}
+
+/**
+ * Scribeberry SDK — Medical transcription, AI note generation, and realtime speech-to-text.
+ *
+ * Universal package: works in both Node.js and browser environments.
+ *
+ * @example Server-side (Node.js)
+ * ```typescript
+ * import { Scribeberry } from '@scribeberry/sdk';
+ *
+ * const sb = new Scribeberry({ apiKey: 'sk_live_...' });
+ *
+ * // List templates
+ * const templates = await sb.templates.list();
+ *
+ * // Generate a note
+ * const result = await sb.notes.generate({
+ *   templateId: templates.items[0].id,
+ *   conversationText: 'Patient presents with...',
+ * });
+ *
+ * // Create a temporary token for browser clients
+ * const { token, wsUrl } = await sb.realtime.createToken();
+ * ```
+ *
+ * @example Browser with token callback (recommended)
+ * ```typescript
+ * import { Scribeberry } from '@scribeberry/sdk';
+ *
+ * const sb = new Scribeberry({
+ *   getRealtimeToken: async () => {
+ *     const res = await fetch('/api/realtime-token', { method: 'POST' });
+ *     return res.json(); // { token, expiresAt }
+ *   },
+ * });
+ *
+ * const session = sb.realtime.transcribe({ language: 'en-US' });
+ * session.on('final', (segment) => console.log(segment.text));
+ * session.sendAudio(audioChunk);
+ * const result = await session.stop();
+ * ```
+ */
+declare class Scribeberry {
+    private readonly http;
+    /** Manage note templates (requires full API key). */
+    readonly templates: Templates;
+    /** Generate medical notes from text or audio (requires full API key). */
+    readonly notes: Notes;
+    /** Realtime audio transcription via WebSocket. */
+    readonly realtime: Realtime;
+    constructor(config: ScribeberryConfig);
+}
+
+export { AuthenticationError, type CreateRealtimeTokenOptions, type CreateTemplateOptions, type GenerateNoteOptions, type GenerateNoteResult, type ListTemplatesOptions, type Note, type PaginatedResponse, RateLimitError, type RealtimeConfig, type RealtimeSessionEvents, type RealtimeSessionResult, type RealtimeToken, type RealtimeTokenResult, RealtimeTranscriptionSession, Scribeberry, type ScribeberryConfig, ScribeberryError, type Template, type TranscriptSegment };