@dimer47/gladia-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,690 @@
+type JobStatus = 'queued' | 'processing' | 'done' | 'error';
+interface PaginationParams {
+    offset?: number;
+    limit?: number;
+    date?: string;
+    before_date?: string;
+    after_date?: string;
+    status?: JobStatus[];
+    custom_metadata?: Record<string, unknown>;
+}
+interface PaginatedResponse<T> {
+    first: string;
+    current: string;
+    next?: string | null;
+    items: T[];
+}
+interface FileResponse {
+    id?: string;
+    filename?: string | null;
+    source?: string | null;
+    audio_duration?: number | null;
+    number_of_channels?: number | null;
+}
+interface GladiaClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    /** Custom WebSocket constructor (for Node < 21, pass `ws`) */
+    WebSocket?: unknown;
+}
+
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(config: HttpClientConfig);
+    get<T>(path: string, query?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    post<T>(path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+    postForm<T>(path: string, formData: FormData, signal?: AbortSignal): Promise<T>;
+    delete(path: string, signal?: AbortSignal): Promise<void>;
+    getBlob(path: string, signal?: AbortSignal): Promise<Blob>;
+    private buildUrl;
+    private headers;
+    private request;
+    private throwApiError;
+}
+
+interface AudioMetadata {
+    id: string;
+    filename: string;
+    source: string;
+    extension: string;
+    size: number;
+    audio_duration: number;
+    number_of_channels: number;
+}
+interface UploadResponse {
+    audio_url: string;
+    audio_metadata: AudioMetadata;
+}
+
+declare class UploadResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Upload a file (Blob, File, or Buffer) to Gladia.
+     */
+    fromFile(file: Blob, filename?: string, signal?: AbortSignal): Promise<UploadResponse>;
+    /**
+     * Upload from a remote URL.
+     */
+    fromUrl(audioUrl: string, signal?: AbortSignal): Promise<UploadResponse>;
+}
+
+interface LanguageConfig {
+    languages?: string[];
+    code_switching?: boolean;
+}
+interface CustomVocabularyEntry {
+    value: string;
+    intensity?: number;
+    pronunciations?: string[];
+    language?: string;
+}
+interface CustomVocabularyConfig {
+    vocabulary?: (string | CustomVocabularyEntry)[];
+    default_intensity?: number;
+}
+interface DiarizationConfig {
+    number_of_speakers?: number;
+    min_speakers?: number;
+    max_speakers?: number;
+}
+type SubtitleFormat = 'srt' | 'vtt';
+type SubtitleStyle = 'default' | 'compliance';
+interface SubtitlesConfig {
+    formats?: SubtitleFormat[];
+    minimum_duration?: number;
+    maximum_duration?: number;
+    maximum_characters_per_row?: number;
+    maximum_rows_per_caption?: number;
+    style?: SubtitleStyle;
+}
+type TranslationModel = 'base' | 'enhanced';
+interface TranslationConfig {
+    target_languages: string[];
+    model?: TranslationModel;
+    match_original_utterances?: boolean;
+    lipsync?: boolean;
+    context_adaptation?: boolean;
+    informal?: boolean;
+    context?: string;
+}
+type SummarizationType = 'general' | 'bullet_points' | 'concise';
+interface SummarizationConfig {
+    type?: SummarizationType;
+}
+interface CustomSpellingConfig {
+    spelling_dictionary: Record<string, string[]>;
+}
+interface StructuredDataExtractionConfig {
+    classes: string[];
+}
+interface AudioToLlmConfig {
+    prompts: string[];
+}
+type PiiProcessedTextType = 'MASK' | 'MARKER';
+interface PiiRedactionConfig {
+    entity_types?: string[];
+    processed_text_type?: PiiProcessedTextType;
+}
+type CallbackMethod = 'POST' | 'PUT';
+interface CallbackConfig {
+    url: string;
+    method?: CallbackMethod;
+}
+interface PreProcessingConfig {
+    audio_enhancer?: boolean;
+    speech_threshold?: number;
+}
+interface RealtimeProcessingConfig {
+    custom_vocabulary?: boolean;
+    custom_vocabulary_config?: CustomVocabularyConfig;
+    custom_spelling?: boolean;
+    custom_spelling_config?: CustomSpellingConfig;
+    translation?: boolean;
+    translation_config?: TranslationConfig;
+    named_entity_recognition?: boolean;
+    sentiment_analysis?: boolean;
+}
+interface PostProcessingConfig {
+    summarization?: boolean;
+    summarization_config?: SummarizationConfig;
+    chapterization?: boolean;
+}
+interface MessagesConfig {
+    receive_partial_transcripts?: boolean;
+    receive_final_transcripts?: boolean;
+    receive_speech_events?: boolean;
+    receive_pre_processing_events?: boolean;
+    receive_realtime_processing_events?: boolean;
+    receive_post_processing_events?: boolean;
+    receive_acknowledgments?: boolean;
+    receive_errors?: boolean;
+    receive_lifecycle_events?: boolean;
+}
+interface LiveCallbackConfig {
+    url: string;
+    receive_partial_transcripts?: boolean;
+    receive_final_transcripts?: boolean;
+    receive_speech_events?: boolean;
+    receive_pre_processing_events?: boolean;
+    receive_realtime_processing_events?: boolean;
+    receive_post_processing_events?: boolean;
+    receive_acknowledgments?: boolean;
+    receive_errors?: boolean;
+    receive_lifecycle_events?: boolean;
+}
+
+interface Word {
+    word: string;
+    start: number;
+    end: number;
+    confidence: number;
+}
+interface Utterance {
+    start: number;
+    end: number;
+    confidence: number;
+    channel: number;
+    speaker?: number | null;
+    words: Word[];
+    text: string;
+    language: string;
+}
+interface SubtitleFile {
+    format: SubtitleFormat;
+    subtitles: string;
+}
+interface TranscriptionDTO {
+    full_transcript: string;
+    languages: string[];
+    utterances: Utterance[];
+    sentences?: Record<string, unknown>[] | null;
+    subtitles?: SubtitleFile[] | null;
+}
+interface TranscriptionMetadata {
+    audio_duration: number;
+    number_of_distinct_channels: number;
+    billing_time: number;
+    transcription_time: number;
+}
+
+interface AddonError {
+    status_code: number;
+    exception: string;
+    message: string;
+}
+interface AddonGenericDTO {
+    success: boolean;
+    is_empty: boolean;
+    exec_time: number;
+    error?: AddonError;
+    results?: unknown;
+}
+interface TranslationResultEntry {
+    error?: AddonError;
+    full_transcript: string;
+    languages: string[];
+    sentences?: Record<string, unknown>[] | null;
+    subtitles?: SubtitleFile[] | null;
+    words: Word[];
+    utterances: Utterance[];
+}
+interface AddonTranslationDTO {
+    success: boolean;
+    is_empty: boolean;
+    exec_time: number;
+    error?: AddonError;
+    results?: TranslationResultEntry[] | null;
+}
+interface AddonSummarizationDTO {
+    success: boolean;
+    is_empty: boolean;
+    exec_time: number;
+    error?: AddonError;
+    results?: string | null;
+}
+type Sentiment = 'positive' | 'negative' | 'neutral' | 'mixed' | 'unknown';
+interface SentimentAnalysisEntry {
+    text?: string;
+    sentiment?: Sentiment;
+    emotion?: string;
+    start?: number;
+    end?: number;
+    channel?: number;
+    speaker?: number;
+}
+interface AddonSentimentAnalysisDTO {
+    success: boolean;
+    is_empty: boolean;
+    exec_time: number;
+    error?: AddonError;
+    results?: SentimentAnalysisEntry[] | null;
+}
+interface NerEntity {
+    entity_type?: string;
+    text?: string;
+    start?: number;
+    end?: number;
+}
+interface AddonNerDTO {
+    success: boolean;
+    is_empty: boolean;
+    exec_time: number;
+    error?: AddonError;
+    results?: NerEntity[] | null;
+}
+interface Chapter {
+    summary?: string;
+    headline?: string;
+    gist?: string;
+    keywords?: string[];
+    start?: number;
+    end?: number;
+}
+interface AddonChapterizationDTO {
+    success: boolean;
+    is_empty: boolean;
+    exec_time: number;
+    error?: AddonError;
+    results?: Chapter[] | null;
+}
+interface AudioToLlmResultEntry {
+    success?: boolean;
+    is_empty?: boolean;
+    results?: {
+        prompt?: string;
+        response?: string;
+    };
+    exec_time?: number;
+    error?: AddonError;
+}
+interface AddonAudioToLlmDTO {
+    success: boolean;
+    is_empty: boolean;
+    exec_time: number;
+    error?: AddonError;
+    results?: AudioToLlmResultEntry[] | null;
+}
+
+interface PreRecordedRequest {
+    audio_url: string;
+    language_config?: LanguageConfig;
+    custom_vocabulary?: boolean;
+    custom_vocabulary_config?: CustomVocabularyConfig;
+    sentences?: boolean;
+    punctuation_enhanced?: boolean;
+    diarization?: boolean;
+    diarization_config?: DiarizationConfig;
+    subtitles?: boolean;
+    subtitles_config?: SubtitlesConfig;
+    translation?: boolean;
+    translation_config?: TranslationConfig;
+    summarization?: boolean;
+    summarization_config?: SummarizationConfig;
+    sentiment_analysis?: boolean;
+    moderation?: boolean;
+    named_entity_recognition?: boolean;
+    chapterization?: boolean;
+    name_consistency?: boolean;
+    custom_spelling?: boolean;
+    custom_spelling_config?: CustomSpellingConfig;
+    structured_data_extraction?: boolean;
+    structured_data_extraction_config?: StructuredDataExtractionConfig;
+    audio_to_llm?: boolean;
+    audio_to_llm_config?: AudioToLlmConfig;
+    display_mode?: boolean;
+    pii_redaction?: boolean;
+    pii_redaction_config?: PiiRedactionConfig;
+    callback?: boolean;
+    callback_config?: CallbackConfig;
+    custom_metadata?: Record<string, unknown>;
+}
+interface PreRecordedCreatedResponse {
+    id: string;
+    result_url: string;
+}
+interface TranscriptionResult {
+    metadata?: TranscriptionMetadata;
+    transcription?: TranscriptionDTO;
+    translation?: AddonTranslationDTO | null;
+    summarization?: AddonSummarizationDTO | null;
+    moderation?: AddonGenericDTO | null;
+    named_entity_recognition?: AddonNerDTO | null;
+    sentiment_analysis?: AddonSentimentAnalysisDTO | null;
+    chapterization?: AddonChapterizationDTO | null;
+    diarization?: AddonGenericDTO | null;
+    name_consistency?: AddonGenericDTO | null;
+    speaker_reidentification?: AddonGenericDTO | null;
+    structured_data_extraction?: AddonGenericDTO | null;
+    audio_to_llm?: AddonAudioToLlmDTO | null;
+    display_mode?: AddonGenericDTO | null;
+}
+interface PreRecordedResponse {
+    id: string;
+    request_id: string;
+    version: number;
+    status: JobStatus;
+    created_at: string;
+    completed_at?: string | null;
+    custom_metadata?: Record<string, unknown>;
+    error_code?: number | null;
+    post_session_metadata: Record<string, unknown>;
+    kind: 'pre-recorded';
+    file?: FileResponse | null;
+    request_params?: Record<string, unknown> | null;
+    result?: TranscriptionResult | null;
+}
+
+interface TranscribeOptions extends PreRecordedRequest {
+    /** Called on each poll with the current response */
+    onPoll?: (response: PreRecordedResponse) => void;
+    /** Maximum polling time in ms */
+    pollTimeout?: number;
+    signal?: AbortSignal;
+}
+declare class PreRecordedResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a pre-recorded transcription job.
+     */
+    create(request: PreRecordedRequest, signal?: AbortSignal): Promise<PreRecordedCreatedResponse>;
+    /**
+     * Get a pre-recorded transcription by ID.
+     */
+    get(id: string, signal?: AbortSignal): Promise<PreRecordedResponse>;
+    /**
+     * List pre-recorded transcriptions with pagination.
+     */
+    list(params?: PaginationParams, signal?: AbortSignal): Promise<PaginatedResponse<PreRecordedResponse>>;
+    /**
+     * Delete a pre-recorded transcription.
+     */
+    delete(id: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Download the original audio file for a transcription.
+     */
+    getFile(id: string, signal?: AbortSignal): Promise<Blob>;
+    /**
+     * High-level helper: create a job and poll until completion.
+     */
+    transcribe(options: TranscribeOptions): Promise<PreRecordedResponse>;
+}
+
+type LiveEncoding = 'wav/pcm' | 'wav/alaw' | 'wav/ulaw';
+type LiveBitDepth = 8 | 16 | 24 | 32;
+type LiveSampleRate = 8000 | 16000 | 32000 | 44100 | 48000;
+type LiveModel = 'solaria-1';
+type LiveRegion = 'us-west' | 'eu-west';
+interface LiveRequest {
+    encoding?: LiveEncoding;
+    bit_depth?: LiveBitDepth;
+    sample_rate?: LiveSampleRate;
+    channels?: number;
+    model?: LiveModel;
+    endpointing?: number;
+    maximum_duration_without_endpointing?: number;
+    language_config?: LanguageConfig;
+    pre_processing?: PreProcessingConfig;
+    realtime_processing?: RealtimeProcessingConfig;
+    post_processing?: PostProcessingConfig;
+    messages_config?: MessagesConfig;
+    callback?: boolean;
+    callback_config?: LiveCallbackConfig;
+    custom_metadata?: Record<string, unknown>;
+}
+interface LiveCreatedResponse {
+    id: string;
+    created_at: string;
+    url: string;
+}
+interface LiveRequestParams {
+    encoding?: LiveEncoding;
+    bit_depth?: LiveBitDepth;
+    sample_rate?: LiveSampleRate;
+    channels?: number;
+    model?: LiveModel;
+    endpointing?: number;
+    maximum_duration_without_endpointing?: number;
+    language_config?: LanguageConfig;
+    pre_processing?: PreProcessingConfig;
+    realtime_processing?: RealtimeProcessingConfig;
+    post_processing?: PostProcessingConfig;
+    messages_config?: MessagesConfig;
+    callback?: boolean;
+    callback_config?: LiveCallbackConfig;
+}
+interface LiveTranscriptionResult {
+    metadata?: TranscriptionMetadata;
+    transcription?: TranscriptionDTO;
+    translation?: AddonTranslationDTO | null;
+    summarization?: AddonSummarizationDTO | null;
+    named_entity_recognition?: AddonNerDTO | null;
+    sentiment_analysis?: AddonSentimentAnalysisDTO | null;
+    chapterization?: AddonChapterizationDTO | null;
+    messages?: Record<string, unknown>[];
+}
+interface LiveResponse {
+    id: string;
+    request_id: string;
+    version: number;
+    status: JobStatus;
+    created_at: string;
+    completed_at?: string | null;
+    custom_metadata?: Record<string, unknown>;
+    error_code?: number | null;
+    post_session_metadata: Record<string, unknown>;
+    kind: 'live';
+    file?: FileResponse | null;
+    request_params?: LiveRequestParams | null;
+    result?: LiveTranscriptionResult | null;
+}
+
+interface LiveBaseMessage {
+    type: string;
+    [key: string]: unknown;
+}
+interface LiveTranscriptMessage {
+    type: 'transcript';
+    transcription: {
+        type: 'partial' | 'final';
+        text: string;
+        language: string;
+        time_begin: number;
+        time_end: number;
+        utterance: Utterance;
+    };
+}
+interface LiveSpeechBeginMessage {
+    type: 'speech-begin';
+}
+interface LiveSpeechEndMessage {
+    type: 'speech-end';
+}
+interface LivePreProcessingMessage {
+    type: 'pre-processing';
+    [key: string]: unknown;
+}
+interface LiveRealtimeProcessingMessage {
+    type: 'realtime-processing';
+    [key: string]: unknown;
+}
+interface LivePostProcessingMessage {
+    type: 'post-processing';
+    [key: string]: unknown;
+}
+interface LiveReadyMessage {
+    type: 'ready';
+}
+interface LiveDoneMessage {
+    type: 'done';
+}
+interface LiveAcknowledgmentMessage {
+    type: 'acknowledgment';
+    [key: string]: unknown;
+}
+interface LiveErrorMessage {
+    type: 'error';
+    code?: number;
+    message?: string;
+    [key: string]: unknown;
+}
+interface LiveEventMap {
+    'transcript:partial': LiveTranscriptMessage;
+    'transcript:final': LiveTranscriptMessage;
+    'speech-begin': LiveSpeechBeginMessage;
+    'speech-end': LiveSpeechEndMessage;
+    'pre-processing': LivePreProcessingMessage;
+    'realtime-processing': LiveRealtimeProcessingMessage;
+    'post-processing': LivePostProcessingMessage;
+    ready: LiveReadyMessage;
+    done: LiveDoneMessage;
+    acknowledgment: LiveAcknowledgmentMessage;
+    error: LiveErrorMessage;
+    message: LiveBaseMessage;
+}
+type LiveEventName = keyof LiveEventMap;
+
+type Listener<T> = (data: T) => void;
+declare class LiveSession {
+    private ws;
+    private listeners;
+    private _closed;
+    private _donePromiseResolve?;
+    private _donePromise;
+    constructor(url: string, WebSocketCtor?: unknown);
+    /**
+     * Register a typed event listener.
+     */
+    on<K extends LiveEventName>(event: K, listener: Listener<LiveEventMap[K]>): this;
+    /**
+     * Remove a typed event listener.
+     */
+    off<K extends LiveEventName>(event: K, listener: Listener<LiveEventMap[K]>): this;
+    /**
+     * Send raw audio data (ArrayBuffer, Uint8Array, or Blob).
+     */
+    sendAudio(data: ArrayBuffer | Uint8Array | Blob): void;
+    /**
+     * Signal end of audio and wait for the server to finish processing.
+     * Returns a promise that resolves when the "done" message is received or the socket closes.
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns true if the WebSocket is closed.
+     */
+    get closed(): boolean;
+    private handleMessage;
+    private emit;
+}
+
+interface LiveStreamOptions extends LiveRequest {
+    region?: LiveRegion;
+    /** Custom WebSocket constructor (for Node < 21, pass `ws`) */
+    WebSocket?: unknown;
+    signal?: AbortSignal;
+}
+declare class LiveResource {
+    private readonly http;
+    private readonly WebSocketCtor?;
+    constructor(http: HttpClient, WebSocketCtor?: unknown);
+    /**
+     * Initialize a live transcription session (returns metadata + WebSocket URL).
+     */
+    init(request?: LiveRequest, options?: {
+        region?: LiveRegion;
+        signal?: AbortSignal;
+    }): Promise<LiveCreatedResponse>;
+    /**
+     * Get a live session by ID.
+     */
+    get(id: string, signal?: AbortSignal): Promise<LiveResponse>;
+    /**
+     * List live sessions with pagination.
+     */
+    list(params?: PaginationParams, signal?: AbortSignal): Promise<PaginatedResponse<LiveResponse>>;
+    /**
+     * Delete a live session.
+     */
+    delete(id: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Download the audio recording of a live session.
+     */
+    getFile(id: string, signal?: AbortSignal): Promise<Blob>;
+    /**
+     * High-level helper: init a session and return a connected LiveSession.
+     */
+    stream(options?: LiveStreamOptions): Promise<LiveSession>;
+}
+
+declare class GladiaClient {
+    readonly upload: UploadResource;
+    readonly preRecorded: PreRecordedResource;
+    readonly live: LiveResource;
+    constructor(config: GladiaClientConfig);
+}
+
+declare class GladiaError extends Error {
+    constructor(message: string);
+}
+interface ApiErrorBody {
+    timestamp?: string;
+    path?: string;
+    request_id?: string;
+    statusCode?: number;
+    message?: string;
+    validation_errors?: string[];
+}
+declare class GladiaApiError extends GladiaError {
+    readonly status: number;
+    readonly body: ApiErrorBody;
+    constructor(status: number, body: ApiErrorBody);
+}
+declare class BadRequestError extends GladiaApiError {
+    readonly validationErrors: string[];
+    constructor(body: ApiErrorBody);
+}
+declare class UnauthorizedError extends GladiaApiError {
+    constructor(body: ApiErrorBody);
+}
+declare class ForbiddenError extends GladiaApiError {
+    constructor(body: ApiErrorBody);
+}
+declare class NotFoundError extends GladiaApiError {
+    constructor(body: ApiErrorBody);
+}
+declare class UnprocessableEntityError extends GladiaApiError {
+    constructor(body: ApiErrorBody);
+}
+declare class GladiaTimeoutError extends GladiaError {
+    constructor(message?: string);
+}
+declare class GladiaWebSocketError extends GladiaError {
+    readonly code?: number;
+    readonly reason?: string;
+    constructor(message: string, code?: number, reason?: string);
+}
+
+interface PollOptions<T> {
+    fn: () => Promise<T>;
+    isDone: (result: T) => boolean;
+    onPoll?: (result: T) => void;
+    /** Initial interval in ms (default: 1000) */
+    interval?: number;
+    /** Multiplier for exponential backoff (default: 1.5) */
+    backoffMultiplier?: number;
+    /** Maximum interval in ms (default: 10000) */
+    maxInterval?: number;
+    /** Maximum total time in ms (default: none) */
+    timeout?: number;
+    signal?: AbortSignal;
+}
+declare function poll<T>(options: PollOptions<T>): Promise<T>;
+declare function isTerminalStatus(status: JobStatus): boolean;
+
+export { type AddonAudioToLlmDTO, type AddonChapterizationDTO, type AddonError, type AddonGenericDTO, type AddonNerDTO, type AddonSentimentAnalysisDTO, type AddonSummarizationDTO, type AddonTranslationDTO, type ApiErrorBody, type AudioMetadata, type AudioToLlmConfig, type AudioToLlmResultEntry, BadRequestError, type CallbackConfig, type CallbackMethod, type Chapter, type CustomSpellingConfig, type CustomVocabularyConfig, type CustomVocabularyEntry, type DiarizationConfig, type FileResponse, ForbiddenError, GladiaApiError, GladiaClient, type GladiaClientConfig, GladiaError, GladiaTimeoutError, GladiaWebSocketError, type JobStatus, type LanguageConfig, type LiveAcknowledgmentMessage, type LiveBaseMessage, type LiveBitDepth, type LiveCallbackConfig, type LiveCreatedResponse, type LiveDoneMessage, type LiveEncoding, type LiveErrorMessage, type LiveEventMap, type LiveEventName, type LiveModel, type LivePostProcessingMessage, type LivePreProcessingMessage, type LiveReadyMessage, type LiveRealtimeProcessingMessage, type LiveRegion, type LiveRequest, type LiveRequestParams, LiveResource, type LiveResponse, type LiveSampleRate, LiveSession, type LiveSpeechBeginMessage, type LiveSpeechEndMessage, type LiveStreamOptions, type LiveTranscriptMessage, type LiveTranscriptionResult, type MessagesConfig, type NerEntity, NotFoundError, type PaginatedResponse, type PaginationParams, type PiiProcessedTextType, type PiiRedactionConfig, type PollOptions, type PostProcessingConfig, type PreProcessingConfig, type PreRecordedCreatedResponse, type PreRecordedRequest, PreRecordedResource, type PreRecordedResponse, type RealtimeProcessingConfig, type Sentiment, type SentimentAnalysisEntry, type StructuredDataExtractionConfig, type SubtitleFile, type SubtitleFormat, type SubtitleStyle, type SubtitlesConfig, type SummarizationConfig, type SummarizationType, type TranscribeOptions, type TranscriptionDTO, type TranscriptionMetadata, type TranscriptionResult, type TranslationConfig, type TranslationModel, type TranslationResultEntry, UnauthorizedError, UnprocessableEntityError, UploadResource, type UploadResponse, type Utterance, type Word, isTerminalStatus, poll };