@scribeberry/sdk 0.2.0

package/dist/index.mjs

@@ -0,0 +1,791 @@
+// src/lib/errors.ts
+var ScribeberryError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "ScribeberryError";
+  }
+};
+var AuthenticationError = class extends ScribeberryError {
+  constructor(message = "Invalid or expired API key") {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends ScribeberryError {
+  constructor(message = "Rate limit exceeded") {
+    super(message, "RATE_LIMIT_EXCEEDED", 429);
+    this.name = "RateLimitError";
+  }
+};
+
+// src/lib/runtime.ts
+var isBrowser = () => typeof window !== "undefined" && typeof window.navigator !== "undefined";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.scribeberry.com";
+var DEFAULT_TIMEOUT = 3e4;
+var TOKEN_REFRESH_BUFFER_MS = 6e4;
+var HttpClient = class {
+  constructor(config) {
+    /** Current realtime token (fetched via callback or static). */
+    this.currentToken = null;
+    /** When the current token expires. */
+    this.tokenExpiresAt = null;
+    /** Active refresh timer. */
+    this.refreshTimer = null;
+    /** Listeners notified on token refresh. */
+    this.tokenRefreshListeners = /* @__PURE__ */ new Set();
+    if (!config.apiKey && !config.getRealtimeToken) {
+      throw new ScribeberryError(
+        "Either apiKey or getRealtimeToken is required",
+        "MISSING_AUTH"
+      );
+    }
+    this.getRealtimeToken = config.getRealtimeToken;
+    this.hasTokenProvider = !!config.getRealtimeToken;
+    if (config.apiKey) {
+      const validPrefixes = ["sk_test_", "sk_live_", "sb_rt_"];
+      if (!validPrefixes.some((p) => config.apiKey.startsWith(p))) {
+        throw new ScribeberryError(
+          "API key must start with sk_test_, sk_live_, or sb_rt_",
+          "INVALID_API_KEY_FORMAT"
+        );
+      }
+    }
+    this.isTemporaryToken = !!config.getRealtimeToken || !!config.apiKey?.startsWith("sb_rt_");
+    if (isBrowser() && config.apiKey && !config.apiKey.startsWith("sb_rt_") && !config.getRealtimeToken) {
+      console.warn(
+        "[Scribeberry] WARNING: Using a permanent API key in the browser is a security risk.\nUse getRealtimeToken callback or sb.realtime.createToken() on your server.\nSee: https://scribeberry.com/docs/realtime#browser-usage"
+      );
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    if (config.apiKey?.startsWith("sb_rt_")) {
+      this.currentToken = config.apiKey;
+    }
+  }
+  /**
+   * The WebSocket URL derived from the base URL.
+   */
+  get wsUrl() {
+    return this.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
+  }
+  /**
+   * Get the current realtime token for WebSocket connections.
+   * If a getRealtimeToken callback is configured, fetches/refreshes as needed.
+   * Otherwise returns the static apiKey.
+   */
+  async getWsToken() {
+    if (this.getRealtimeToken) {
+      if (this.currentToken && this.tokenExpiresAt && Date.now() < this.tokenExpiresAt - TOKEN_REFRESH_BUFFER_MS) {
+        return this.currentToken;
+      }
+      return this.refreshToken();
+    }
+    if (!this.apiKey) {
+      throw new ScribeberryError(
+        "No API key or token available",
+        "MISSING_AUTH"
+      );
+    }
+    return this.apiKey;
+  }
+  /**
+   * Fetch a fresh token from the callback and schedule auto-refresh.
+   */
+  async refreshToken() {
+    if (!this.getRealtimeToken) {
+      throw new ScribeberryError(
+        "No token provider configured",
+        "MISSING_AUTH"
+      );
+    }
+    try {
+      const result = await this.getRealtimeToken();
+      if (!result.token || !result.expiresAt) {
+        throw new ScribeberryError(
+          "getRealtimeToken must return { token, expiresAt }",
+          "INVALID_TOKEN_RESPONSE"
+        );
+      }
+      this.currentToken = result.token;
+      this.tokenExpiresAt = new Date(result.expiresAt).getTime();
+      this.scheduleRefresh();
+      return result.token;
+    } catch (err) {
+      if (err instanceof ScribeberryError) throw err;
+      throw new ScribeberryError(
+        `Failed to fetch realtime token: ${err instanceof Error ? err.message : String(err)}`,
+        "TOKEN_FETCH_FAILED"
+      );
+    }
+  }
+  /**
+   * Register a listener that's called when the token is refreshed.
+   * Used by RealtimeTranscriptionSession to reconnect with the new token.
+   */
+  onTokenRefresh(listener) {
+    this.tokenRefreshListeners.add(listener);
+  }
+  /**
+   * Remove a token refresh listener.
+   */
+  offTokenRefresh(listener) {
+    this.tokenRefreshListeners.delete(listener);
+  }
+  /**
+   * Schedule an automatic token refresh before the current token expires.
+   */
+  scheduleRefresh() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+    }
+    if (!this.tokenExpiresAt || !this.getRealtimeToken) return;
+    const msUntilExpiry = this.tokenExpiresAt - Date.now();
+    const refreshIn = Math.max(msUntilExpiry - TOKEN_REFRESH_BUFFER_MS, 5e3);
+    this.refreshTimer = setTimeout(async () => {
+      try {
+        const token = await this.refreshToken();
+        for (const listener of this.tokenRefreshListeners) {
+          try {
+            listener(token);
+          } catch {
+          }
+        }
+      } catch {
+      }
+    }, refreshIn);
+  }
+  /**
+   * Make an authenticated HTTP request to the Scribeberry API.
+   */
+  async request(method, path, options) {
+    if (this.isTemporaryToken && !this.apiKey?.startsWith("sk_")) {
+      throw new ScribeberryError(
+        "Temporary tokens (sb_rt_*) can only be used for realtime WebSocket connections. Use a full API key (sk_test_*/sk_live_*) for REST API calls.",
+        "INVALID_TOKEN_SCOPE"
+      );
+    }
+    const url = new URL(`${this.baseUrl}/api/v1${path}`);
+    if (options?.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(
+      () => controller.abort(),
+      options?.timeout || this.timeout
+    );
+    try {
+      const fetchFn = await this.getFetch();
+      const response = await fetchFn(url.toString(), {
+        method,
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "scribeberry-sdk/0.2.0"
+        },
+        body: options?.body ? JSON.stringify(options.body) : void 0,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        await this.handleError(response);
+      }
+      if (response.status === 204 || response.headers.get("content-length") === "0") {
+        return {};
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof ScribeberryError) throw error;
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new ScribeberryError("Request timed out", "TIMEOUT", 408);
+      }
+      throw new ScribeberryError(
+        `Network error: ${error instanceof Error ? error.message : "Unknown"}`,
+        "NETWORK_ERROR"
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  async getFetch() {
+    if (typeof globalThis.fetch !== "undefined") {
+      return globalThis.fetch;
+    }
+    try {
+      const { default: crossFetch } = await import("cross-fetch");
+      return crossFetch;
+    } catch {
+      throw new ScribeberryError(
+        'fetch is not available. Upgrade to Node.js >= 18 or install "cross-fetch".',
+        "FETCH_UNAVAILABLE"
+      );
+    }
+  }
+  async handleError(response) {
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      body = { message: response.statusText };
+    }
+    const message = body.message || body.error || response.statusText;
+    switch (response.status) {
+      case 401:
+        throw new AuthenticationError(message);
+      case 429:
+        throw new RateLimitError(message);
+      default:
+        throw new ScribeberryError(
+          message,
+          body.code || `HTTP_${response.status}`,
+          response.status
+        );
+    }
+  }
+};
+
+// src/resources/templates.ts
+var Templates = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List all templates (paginated).
+   */
+  async list(options) {
+    return this.http.request("GET", "/templates", {
+      params: {
+        page: options?.page,
+        pageSize: options?.pageSize,
+        sortBy: options?.sortBy,
+        sortOrder: options?.sortOrder
+      }
+    });
+  }
+  /**
+   * Get a template by ID.
+   */
+  async get(templateId) {
+    return this.http.request("GET", `/templates/${templateId}`);
+  }
+  /**
+   * Create a new template.
+   */
+  async create(options) {
+    return this.http.request("POST", "/templates", { body: options });
+  }
+  /**
+   * Delete a template.
+   */
+  async delete(templateId) {
+    return this.http.request("DELETE", `/templates/${templateId}`);
+  }
+};
+
+// src/resources/notes.ts
+var Notes = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Generate a note from conversation text or audio.
+   *
+   * @param options - Note generation options.
+   * @returns The generated note with optional transcript data.
+   */
+  async generate(options) {
+    const body = {
+      template_id: options.templateId
+    };
+    if (options.conversationText) {
+      body.conversation_text = options.conversationText;
+    }
+    if (options.audioUrl) {
+      body.audioUrl = options.audioUrl;
+    }
+    if (options.sourceLanguage) {
+      body.sourceLanguage = options.sourceLanguage;
+    }
+    if (options.transcriptionQuality) {
+      body.transcriptionQuality = options.transcriptionQuality;
+    }
+    if (options.context) {
+      body.context = options.context;
+    }
+    const response = await this.http.request(
+      "POST",
+      "/notes",
+      { body, timeout: 12e4 }
+      // Notes may take longer (transcription + LLM)
+    );
+    return {
+      note: {
+        markdown: response.note?.markdown || response.markdown || "",
+        text: response.note?.text || response.text || "",
+        structured: response.note?.structured || response.structured || {}
+      },
+      transcript: response.transcript ? {
+        text: response.transcript.text,
+        confidence: response.transcript.confidence,
+        duration: response.transcript.duration,
+        sourceLanguage: response.transcript.sourceLanguage
+      } : void 0,
+      template: {
+        id: response.template?.id || options.templateId,
+        name: response.template?.name || ""
+      }
+    };
+  }
+};
+
+// src/lib/ws-client.ts
+async function createWebSocket(url, protocols) {
+  if (typeof WebSocket !== "undefined") {
+    return new WebSocket(url, protocols);
+  }
+  try {
+    const { default: WS } = await import("ws");
+    return new WS(url, protocols);
+  } catch {
+    throw new Error(
+      'WebSocket is not available. Install the "ws" package: npm install ws'
+    );
+  }
+}
+
+// src/realtime/session.ts
+var RealtimeTranscriptionSession = class {
+  constructor(http, config) {
+    this.http = http;
+    this.config = config;
+    this.ws = null;
+    this._sessionId = null;
+    this._state = "idle";
+    this.segments = [];
+    this.durationSeconds = 0;
+    this.stopResolver = null;
+    // Event handlers
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  /** Current session state. */
+  get state() {
+    return this._state;
+  }
+  /** Session ID (available after `'started'` event). */
+  get sessionId() {
+    return this._sessionId;
+  }
+  /**
+   * Get the full accumulated transcript text at any point during the session.
+   *
+   * @returns Concatenated text from all confirmed segments.
+   */
+  getTranscript() {
+    return this.segments.map((s) => s.text).join(" ");
+  }
+  /**
+   * Get all confirmed transcript segments.
+   *
+   * @returns A copy of the segments array.
+   */
+  getSegments() {
+    return [...this.segments];
+  }
+  /**
+   * 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
+   */
+  async connect() {
+    if (this._state !== "idle") {
+      throw new ScribeberryError(
+        "Session already started",
+        "SESSION_STATE_ERROR"
+      );
+    }
+    this._state = "connecting";
+    return new Promise(async (resolve, reject) => {
+      try {
+        const token = await this.http.getWsToken();
+        const wsUrl = `${this.http.wsUrl}/ws/realtime?token=${encodeURIComponent(token)}`;
+        this.ws = await createWebSocket(wsUrl);
+      } catch (err) {
+        this._state = "idle";
+        const error = new ScribeberryError(
+          `Failed to create WebSocket: ${err instanceof Error ? err.message : String(err)}`,
+          "CONNECTION_ERROR"
+        );
+        reject(error);
+        return;
+      }
+      const connectTimeout = setTimeout(() => {
+        if (this._state === "connecting") {
+          const error = new ScribeberryError(
+            "Connect timeout \u2014 no session:started received",
+            "CONNECT_TIMEOUT"
+          );
+          reject(error);
+          this.emit("error", error);
+          this.cleanup();
+        }
+      }, 1e4);
+      this.ws.onopen = () => {
+        this.send({
+          type: "start",
+          config: {
+            language: this.config.language,
+            enableDiarization: this.config.enableDiarization,
+            templateId: this.config.templateId
+          }
+        });
+      };
+      this.ws.onmessage = (event) => {
+        const raw = typeof event.data === "string" ? event.data : String(event.data);
+        let data;
+        try {
+          data = JSON.parse(raw);
+        } catch {
+          return;
+        }
+        if (data.type === "session:started") {
+          clearTimeout(connectTimeout);
+        }
+        this.handleMessage(data, resolve);
+      };
+      this.ws.onerror = (event) => {
+        clearTimeout(connectTimeout);
+        const error = new ScribeberryError(
+          "WebSocket connection error",
+          "CONNECTION_ERROR"
+        );
+        if (this._state === "connecting") {
+          reject(error);
+        }
+        this.emit("error", error);
+      };
+      this.ws.onclose = (event) => {
+        clearTimeout(connectTimeout);
+        if (this._state === "connecting") {
+          reject(
+            new ScribeberryError(
+              `Connection closed: ${event?.code || "unknown"}`,
+              "CONNECTION_CLOSED"
+            )
+          );
+        }
+        if (this._state !== "stopped") {
+          this._state = "stopped";
+        }
+      };
+    });
+  }
+  /**
+   * 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) {
+    if (this._state !== "active") {
+      throw new ScribeberryError(
+        'Session is not active. Wait for the "started" event before sending audio.',
+        "SESSION_STATE_ERROR"
+      );
+    }
+    this.ws?.send(data);
+  }
+  /**
+   * Stream audio from an async iterable source (e.g., microphone stream).
+   *
+   * @param stream - Async iterable of audio chunks.
+   */
+  async sendStream(stream) {
+    for await (const chunk of stream) {
+      if (this._state !== "active") break;
+      this.sendAudio(chunk);
+    }
+  }
+  /**
+   * Pause audio streaming. The WebSocket connection stays alive.
+   */
+  pause() {
+    this.send({ type: "pause" });
+  }
+  /**
+   * Resume audio streaming after a pause.
+   */
+  resume() {
+    this.send({ type: "resume" });
+  }
+  /**
+   * Request finalization of the current audio buffer.
+   * Forces the server to emit any pending partial results as final.
+   */
+  finalize() {
+    this.send({ type: "finalize" });
+  }
+  /**
+   * 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.
+   */
+  async stop() {
+    if (this._state === "stopped") {
+      return this.buildResult();
+    }
+    this._state = "stopping";
+    return new Promise((resolve) => {
+      this.stopResolver = resolve;
+      this.send({ type: "stop" });
+      setTimeout(() => {
+        if (this.stopResolver) {
+          this.stopResolver(this.buildResult());
+          this.stopResolver = null;
+          this.cleanup();
+        }
+      }, 3e4);
+    });
+  }
+  /**
+   * 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(event, handler) {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.handlers.get(event).add(handler);
+    return this;
+  }
+  /**
+   * Remove an event handler.
+   *
+   * @param event - Event name
+   * @param handler - Handler to remove
+   * @returns `this` for chaining
+   */
+  off(event, handler) {
+    this.handlers.get(event)?.delete(handler);
+    return this;
+  }
+  // --- Internal ---
+  emit(event, ...args) {
+    this.handlers.get(event)?.forEach((handler) => {
+      try {
+        handler(...args);
+      } catch {
+      }
+    });
+  }
+  send(message) {
+    if (this.ws?.readyState === 1) {
+      this.ws.send(JSON.stringify(message));
+    }
+  }
+  handleMessage(data, connectResolve) {
+    switch (data.type) {
+      case "session:started":
+        this._sessionId = data.sessionId;
+        this._state = "active";
+        this.emit("started", data.sessionId);
+        connectResolve?.();
+        break;
+      case "transcript:partial":
+        this.emit("partial", data.text, data.speaker);
+        break;
+      case "transcript:final": {
+        const segment = {
+          text: data.text,
+          speaker: data.speaker,
+          startMs: data.startMs,
+          endMs: data.endMs
+        };
+        this.segments.push(segment);
+        this.emit("final", segment);
+        break;
+      }
+      case "endpoint":
+        this.emit("endpoint");
+        break;
+      case "transcript:full":
+        this.durationSeconds = (data.durationMs || 0) / 1e3;
+        break;
+      case "note:generating":
+        break;
+      case "note:complete":
+        this.note = data.note;
+        this.emit("note", data.note);
+        this.resolveStop();
+        break;
+      case "session:stopped":
+        this.durationSeconds = data.durationSeconds || this.durationSeconds;
+        if (!this.config.templateId) {
+          this.resolveStop();
+        }
+        break;
+      case "error":
+        this.emit(
+          "error",
+          new ScribeberryError(
+            data.message || "Unknown error",
+            data.code || "REALTIME_ERROR"
+          )
+        );
+        break;
+    }
+  }
+  resolveStop() {
+    this._state = "stopped";
+    const result = this.buildResult();
+    this.emit("stopped", result);
+    if (this.stopResolver) {
+      this.stopResolver(result);
+      this.stopResolver = null;
+    }
+    this.cleanup();
+  }
+  buildResult() {
+    return {
+      transcript: this.getTranscript(),
+      segments: this.getSegments(),
+      durationSeconds: this.durationSeconds,
+      note: this.note
+    };
+  }
+  cleanup() {
+    try {
+      this.ws?.close();
+    } catch {
+    }
+    this.ws = null;
+  }
+};
+
+// src/realtime/index.ts
+var Realtime = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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_*)
+   */
+  async createToken(options = {}) {
+    if (isBrowser()) {
+      throw new ScribeberryError(
+        "createToken() is only available in Node.js server environments. Call this from your backend and pass the resulting token to the browser.",
+        "SERVER_ONLY"
+      );
+    }
+    if (this.http.isTemporaryToken) {
+      throw new ScribeberryError(
+        "Cannot create a token using a temporary token. Use a full API key (sk_test_*/sk_live_*).",
+        "INVALID_TOKEN_SCOPE"
+      );
+    }
+    return this.http.request("POST", "/realtime/tokens", {
+      body: {
+        expiresInSeconds: options.expiresInSeconds
+      }
+    });
+  }
+  /**
+   * 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 = {}) {
+    const session = new RealtimeTranscriptionSession(this.http, config);
+    session.connect().catch(() => {
+    });
+    return session;
+  }
+};
+
+// src/index.ts
+var Scribeberry = class {
+  constructor(config) {
+    this.http = new HttpClient(config);
+    this.templates = new Templates(this.http);
+    this.notes = new Notes(this.http);
+    this.realtime = new Realtime(this.http);
+  }
+};
+export {
+  AuthenticationError,
+  RateLimitError,
+  RealtimeTranscriptionSession,
+  Scribeberry,
+  ScribeberryError
+};