@veroai/transcribe 1.0.0

package/README.md

@@ -0,0 +1,217 @@
+# @veroai/transcribe
+
+Official Node.js/TypeScript SDK for the VeroTranscribe API.
+
+## Installation
+
+```bash
+npm install @veroai/transcribe
+```
+
+## Quick Start
+
+```typescript
+import { VeroTranscribe } from '@veroai/transcribe';
+
+const client = new VeroTranscribe({
+  apiKey: process.env.VERO_API_KEY,
+});
+
+// Transcribe an audio file
+const result = await client.transcriptions.transcribe({
+  audioUrl: 'https://example.com/audio.mp3',
+  language: 'en',
+  aiType: 'basic',
+});
+
+console.log(result.transcript.text);
+console.log(result.analysis);
+```
+
+## Configuration
+
+```typescript
+const client = new VeroTranscribe({
+  apiKey: 'vt_sk_...',           // Required: Your API key
+  baseUrl: 'https://custom.url', // Optional: Custom API base URL
+  timeout: 30000,                // Optional: Request timeout in ms (default: 30000)
+});
+```
+
+## Transcriptions
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `transcriptions.create(params)` | Create a new transcription job |
+| `transcriptions.get(id)` | Get a transcription by ID |
+| `transcriptions.list(params?)` | List all transcriptions |
+| `transcriptions.delete(id)` | Delete a transcription |
+| `transcriptions.waitForCompletion(id, options?)` | Poll until transcription completes |
+| `transcriptions.transcribe(params, options?)` | Create and wait for completion |
+
+### Create a Transcription
+
+```typescript
+const transcription = await client.transcriptions.create({
+  audioUrl: 'https://example.com/audio.mp3',
+  language: 'en',        // 'en' | 'he' | 'es' | 'auto'
+  aiType: 'basic',       // 'none' | 'basic' | 'coach'
+  saveTranscript: false,
+  webhookUrl: 'https://your-server.com/webhook',
+  metadata: { callId: '123' },
+});
+```
+
+### Get a Transcription
+
+```typescript
+const transcription = await client.transcriptions.get('transcription-id');
+console.log(transcription.status);    // 'pending' | 'processing' | 'completed' | 'failed'
+console.log(transcription.transcript); // { text, segments }
+console.log(transcription.analysis);   // { summary, keyPoints, sentiment }
+```
+
+### List Transcriptions
+
+```typescript
+const { data, total } = await client.transcriptions.list({
+  limit: 20,
+  offset: 0,
+  status: 'completed',
+});
+```
+
+### Wait for Completion
+
+```typescript
+const result = await client.transcriptions.waitForCompletion('transcription-id', {
+  pollInterval: 2000,     // Poll every 2s (default)
+  maxWaitTime: 300000,    // Timeout after 5min (default)
+  onProgress: (t) => console.log(`Status: ${t.status}`),
+});
+```
+
+### Transcribe (Create + Wait)
+
+```typescript
+const result = await client.transcriptions.transcribe({
+  audioUrl: 'https://example.com/audio.mp3',
+  language: 'en',
+  aiType: 'coach',
+});
+
+// Returns the completed transcription with transcript and analysis
+console.log(result.transcript.text);
+console.log(result.analysis.summary);
+console.log(result.analysis.actionItems);
+```
+
+## Webhooks
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `webhooks.create(params)` | Create a webhook endpoint |
+| `webhooks.get(id)` | Get a webhook by ID |
+| `webhooks.list()` | List all webhooks |
+| `webhooks.delete(id)` | Delete a webhook |
+
+### Create a Webhook
+
+```typescript
+const webhook = await client.webhooks.create({
+  url: 'https://your-server.com/webhook',
+  events: ['transcription.completed', 'transcription.failed'],
+});
+
+// Save the secret - only shown once
+console.log(webhook.secret); // 'whsec_...'
+```
+
+### Verify Webhook Signatures
+
+```typescript
+import { createWebhookVerifier } from '@veroai/transcribe';
+
+const verifier = createWebhookVerifier(process.env.WEBHOOK_SECRET);
+
+app.post('/webhook', async (req, res) => {
+  const isValid = await verifier.verify(
+    req.body,
+    req.headers['x-webhook-signature']
+  );
+
+  if (!isValid) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  const event = JSON.parse(req.body);
+  // Handle event...
+});
+```
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `transcription.created` | Transcription job created |
+| `transcription.completed` | Transcription finished successfully |
+| `transcription.failed` | Transcription failed |
+| `analysis.completed` | AI analysis completed |
+
+## Usage
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `usage.get()` | Get current billing period usage |
+
+```typescript
+const usage = await client.usage.get();
+
+console.log(usage.transcriptionMinutes);
+console.log(usage.estimatedCost.total);
+```
+
+## Error Handling
+
+```typescript
+import { VeroAPIError } from '@veroai/transcribe';
+
+try {
+  await client.transcriptions.create({ audioUrl: 'invalid' });
+} catch (error) {
+  if (error instanceof VeroAPIError) {
+    console.error(error.code);    // 'invalid_request'
+    console.error(error.message); // 'The audio URL is not accessible'
+    console.error(error.status);  // 400
+  }
+}
+```
+
+## Types
+
+All types are exported for TypeScript users:
+
+```typescript
+import type {
+  Transcription,
+  TranscriptionStatus,
+  Transcript,
+  Analysis,
+  AIType,
+  Language,
+  CreateTranscriptionParams,
+  Webhook,
+  WebhookEvent,
+  Usage,
+} from '@veroai/transcribe';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,492 @@
+interface VeroTranscribeConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+type TranscriptionStatus = 'pending' | 'processing' | 'completed' | 'failed';
+type AIType = 'none' | 'basic' | 'coach';
+type Language = 'en' | 'he' | 'es' | 'auto';
+interface WordTimestamp {
+    word: string;
+    start: number;
+    end: number;
+}
+interface TranscriptionSegment {
+    speaker: string;
+    text: string;
+    start: number;
+    end: number;
+}
+interface Transcript {
+    text: string;
+    segments: TranscriptionSegment[];
+    words?: WordTimestamp[];
+    language: string;
+    duration: number;
+}
+interface Analysis {
+    summary: string;
+    outcome: {
+        status: string;
+        reason: string;
+        followUpPotential: string;
+    };
+    sentiment: {
+        initial: number;
+        final: number;
+        average: number;
+    };
+    keyPhrases: string[];
+    agentActions?: Array<{
+        action: string;
+        timestamp: string;
+    }>;
+    participants?: {
+        agent?: string;
+        customer?: string;
+    };
+    emotions?: {
+        customer: Array<{
+            emotion: string;
+            intensity: string;
+        }>;
+        agent: Array<{
+            emotion: string;
+            intensity: string;
+        }>;
+    };
+    coaching?: {
+        suggestions: Array<{
+            item: string;
+            timestamp?: string;
+            severity: 'low' | 'medium' | 'high';
+        }>;
+        performance: {
+            clarity: number;
+            empathy: number;
+            compliance: number;
+            professionalism: number;
+        };
+        behavioral?: {
+            talkListenRatio: number;
+            questionsAsked: {
+                open: number;
+                closed: number;
+            };
+            interruptions: number;
+            speakingPace: number;
+            empathyStatements: number;
+        };
+    };
+}
+interface Transcription {
+    id: string;
+    externalId?: string;
+    status: TranscriptionStatus;
+    durationSeconds?: number;
+    language: Language;
+    diarize?: boolean;
+    aiType?: AIType;
+    saveTranscript?: boolean;
+    transcript?: Transcript;
+    analysis?: Analysis;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    completedAt?: string;
+    errorMessage?: string;
+}
+interface CreateTranscriptionParams {
+    language?: Language;
+    diarize?: boolean;
+    aiAnalysis?: AIType;
+    saveTranscript?: boolean;
+    externalId?: string;
+    webhookUrl?: string;
+    metadata?: Record<string, unknown>;
+    /** URL to fetch audio from. When provided, transcription starts immediately without needing upload(). */
+    audioUrl?: string;
+}
+type TranscriptionProvider = 'replicate' | 'elevenlabs' | 'runpod';
+interface UploadAudioParams {
+    provider?: TranscriptionProvider;
+}
+interface UploadAudioResponse {
+    id: string;
+    status: TranscriptionStatus;
+}
+interface ListTranscriptionsParams {
+    limit?: number;
+    offset?: number;
+    status?: TranscriptionStatus;
+    aiAnalysis?: AIType;
+    from?: Date | string;
+    to?: Date | string;
+}
+interface TranscriptionListItem {
+    id: string;
+    externalId?: string;
+    status: TranscriptionStatus;
+    durationSeconds?: number;
+    language: string;
+    aiType?: AIType;
+    createdAt: string;
+    completedAt?: string;
+}
+interface ListTranscriptionsResponse {
+    data: TranscriptionListItem[];
+    pagination: {
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+type WebhookEvent = 'transcription.created' | 'transcription.processing' | 'transcription.completed' | 'transcription.failed' | 'analysis.completed';
+interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEvent[];
+    secret?: string;
+    isActive: boolean;
+    createdAt: string;
+}
+interface CreateWebhookParams {
+    url: string;
+    events: WebhookEvent[];
+}
+interface UpdateWebhookParams {
+    url?: string;
+    events?: WebhookEvent[];
+    isActive?: boolean;
+}
+interface WebhookDelivery {
+    id: string;
+    eventType: WebhookEvent;
+    statusCode: number | null;
+    success: boolean;
+    attempts: number;
+    createdAt: string;
+}
+interface ListWebhooksResponse {
+    data: Webhook[];
+}
+interface ListWebhookDeliveriesResponse {
+    data: WebhookDelivery[];
+}
+interface UsagePeriod {
+    start: string;
+    end: string;
+}
+type PackageSlug = 'starter' | 'standard' | 'insights' | 'pro';
+interface PackageBreakdown {
+    minutes: number;
+    cost: number;
+    count: number;
+}
+interface PackageRates {
+    starter: number;
+    standard: number;
+    insights: number;
+    pro: number;
+}
+interface Usage {
+    period: UsagePeriod;
+    totalMinutes: number;
+    totalCost: number;
+    packages: Record<PackageSlug, PackageBreakdown>;
+    rates: PackageRates;
+}
+interface UsageHistoryRecord {
+    date: string;
+    recordType: string;
+    total: number;
+}
+interface UsageHistoryResponse {
+    data: UsageHistoryRecord[];
+}
+interface UsageHistoryParams {
+    days?: number;
+}
+interface BulkUploadParams {
+    language?: Language;
+    diarize?: boolean;
+    aiAnalysis?: AIType;
+    saveTranscript?: boolean;
+    provider?: TranscriptionProvider;
+    /** Optional per-file metadata, keyed by filename */
+    fileMetadata?: Record<string, {
+        externalId?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+interface BulkUploadResultItem {
+    filename: string;
+    transcriptionId?: string;
+    status: 'queued' | 'failed';
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+interface BulkUploadResponse {
+    batchId: string;
+    totalFiles: number;
+    results: BulkUploadResultItem[];
+    summary: {
+        queued: number;
+        failed: number;
+    };
+}
+interface BulkTranscribeOptions {
+    pollInterval?: number;
+    maxWaitTime?: number;
+    /** Called when an individual file's transcription updates */
+    onFileProgress?: (filename: string, transcription: Transcription) => void;
+    /** Called when any transcription in the batch completes or fails */
+    onBatchProgress?: (completed: number, total: number, results: Map<string, Transcription | Error>) => void;
+    /** How many transcriptions to poll in parallel (default: 5) */
+    concurrency?: number;
+}
+interface BulkTranscribeResult {
+    batchId: string;
+    completed: Transcription[];
+    failed: Array<{
+        filename: string;
+        transcriptionId?: string;
+        error: Error;
+    }>;
+}
+declare class VeroAPIError extends Error {
+    code: string;
+    status: number;
+    constructor(message: string, code: string, status: number);
+}
+
+declare class HttpClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(config: VeroTranscribeConfig);
+    private request;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    postFormData<T>(path: string, formData: FormData): Promise<T>;
+}
+
+declare class TranscriptionsResource {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Create a new transcription.
+     * If audioUrl is provided, transcription starts immediately.
+     * Otherwise, use upload() to provide the audio file.
+     */
+    create(params: CreateTranscriptionParams): Promise<Transcription>;
+    /**
+     * Get a transcription by ID
+     */
+    get(id: string): Promise<Transcription>;
+    /**
+     * List all transcriptions
+     */
+    list(params?: ListTranscriptionsParams): Promise<ListTranscriptionsResponse>;
+    /**
+     * Delete a transcription
+     */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Upload an audio file for an existing transcription
+     * This enqueues the transcription for processing
+     */
+    upload(id: string, audio: File | Blob, params?: UploadAudioParams): Promise<UploadAudioResponse>;
+    /**
+     * Create a transcription, upload audio, and wait for completion
+     * Convenience method that combines create(), upload(), and waitForCompletion()
+     */
+    transcribeFile(audio: File | Blob, params?: CreateTranscriptionParams & UploadAudioParams, options?: {
+        pollInterval?: number;
+        maxWaitTime?: number;
+        onProgress?: (transcription: Transcription) => void;
+    }): Promise<Transcription>;
+    /**
+     * Wait for a transcription to complete
+     * Polls the API at regular intervals until the transcription is completed or failed
+     */
+    waitForCompletion(id: string, options?: {
+        pollInterval?: number;
+        maxWaitTime?: number;
+        onProgress?: (transcription: Transcription) => void;
+    }): Promise<Transcription>;
+    /**
+     * Create a transcription from a URL and wait for it to complete.
+     * When audioUrl is provided, transcription starts immediately.
+     *
+     * @example
+     * ```ts
+     * const result = await vero.transcriptions.transcribe({
+     *   audioUrl: 'https://example.com/audio.mp3',
+     *   language: 'en',
+     * })
+     * ```
+     */
+    transcribe(params: CreateTranscriptionParams & {
+        audioUrl: string;
+    }, options?: {
+        pollInterval?: number;
+        maxWaitTime?: number;
+        onProgress?: (transcription: Transcription) => void;
+    }): Promise<Transcription>;
+    /**
+     * Upload multiple audio files for transcription in a single batch.
+     * Returns immediately after files are queued for processing.
+     *
+     * @example
+     * ```ts
+     * const result = await vero.transcriptions.bulkUpload(
+     *   [file1, file2, file3],
+     *   { language: 'en', aiAnalysis: 'basic' }
+     * )
+     * console.log(`Queued ${result.summary.queued} files`)
+     * ```
+     */
+    bulkUpload(files: File[] | Blob[] | Array<{
+        file: File | Blob;
+        name?: string;
+    }>, params?: BulkUploadParams): Promise<BulkUploadResponse>;
+    /**
+     * Upload multiple files and wait for all to complete.
+     * Handles partial failures gracefully - returns both completed and failed transcriptions.
+     *
+     * @example
+     * ```ts
+     * const result = await vero.transcriptions.bulkTranscribe(
+     *   [file1, file2, file3],
+     *   { language: 'en' },
+     *   {
+     *     onBatchProgress: (completed, total) => {
+     *       console.log(`Progress: ${completed}/${total}`)
+     *     }
+     *   }
+     * )
+     * console.log(`Completed: ${result.completed.length}, Failed: ${result.failed.length}`)
+     * ```
+     */
+    bulkTranscribe(files: File[] | Blob[] | Array<{
+        file: File | Blob;
+        name?: string;
+    }>, params?: BulkUploadParams, options?: BulkTranscribeOptions): Promise<BulkTranscribeResult>;
+    /**
+     * Wait for multiple transcriptions to complete.
+     * Polls in parallel with configurable concurrency.
+     */
+    waitForBatch(items: Array<{
+        id: string;
+        filename?: string;
+    }>, options?: BulkTranscribeOptions): Promise<Map<string, Transcription | Error>>;
+}
+
+declare class WebhooksResource {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Create a new webhook endpoint
+     */
+    create(params: CreateWebhookParams): Promise<Webhook>;
+    /**
+     * Get a webhook by ID
+     */
+    get(id: string): Promise<Webhook>;
+    /**
+     * List all webhooks
+     */
+    list(): Promise<ListWebhooksResponse>;
+    /**
+     * Update a webhook
+     */
+    update(id: string, params: UpdateWebhookParams): Promise<Webhook>;
+    /**
+     * Delete a webhook
+     */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get delivery history for a webhook (last 10)
+     */
+    deliveries(id: string): Promise<ListWebhookDeliveriesResponse>;
+}
+/**
+ * Helper function to verify webhook signatures in Node.js environments.
+ * The signature is computed over `${timestamp}.${body}` using HMAC-SHA256.
+ *
+ * @param secret - The webhook secret (shown once at creation)
+ *
+ * @example
+ * ```typescript
+ * const verifier = createWebhookVerifier('whsec_...')
+ * const isValid = await verifier.verify(rawBody, signatureHeader, timestampHeader)
+ * ```
+ */
+declare function createWebhookVerifier(secret: string): {
+    verify: (body: string, signature: string, timestamp: string) => Promise<boolean>;
+};
+
+declare class UsageResource {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Get usage statistics for the current billing period
+     */
+    get(): Promise<Usage>;
+    /**
+     * Get usage history (daily breakdown)
+     * @param params.days - Number of days to look back (default: 30)
+     */
+    history(params?: UsageHistoryParams): Promise<UsageHistoryResponse>;
+}
+
+declare class VeroTranscribe {
+    /**
+     * Transcriptions API
+     * Create, retrieve, list, and delete transcriptions
+     */
+    readonly transcriptions: TranscriptionsResource;
+    /**
+     * Webhooks API
+     * Manage webhook endpoints for receiving transcription events
+     */
+    readonly webhooks: WebhooksResource;
+    /**
+     * Usage API
+     * Get usage statistics and billing information
+     */
+    readonly usage: UsageResource;
+    /**
+     * Create a new VeroTranscribe client
+     *
+     * @param config - Configuration options
+     * @param config.apiKey - Your VeroTranscribe API key (required)
+     * @param config.baseUrl - Custom API base URL (optional, defaults to https://verotranscribe-api.siply.workers.dev)
+     * @param config.timeout - Request timeout in milliseconds (optional, defaults to 30000)
+     *
+     * @example
+     * ```typescript
+     * const client = new VeroTranscribe({
+     *   apiKey: process.env.VERO_API_KEY,
+     * });
+     *
+     * const transcription = await client.transcriptions.create({
+     *   language: 'en',
+     *   aiAnalysis: 'basic',
+     * });
+     *
+     * await client.transcriptions.upload(transcription.id, audioFile);
+     * ```
+     */
+    constructor(config: VeroTranscribeConfig);
+}
+
+export { type AIType, type Analysis, type CreateTranscriptionParams, type CreateWebhookParams, type Language, type ListTranscriptionsParams, type ListTranscriptionsResponse, type ListWebhookDeliveriesResponse, type ListWebhooksResponse, type PackageBreakdown, type PackageRates, type PackageSlug, type Transcript, type Transcription, type TranscriptionListItem, type TranscriptionProvider, type TranscriptionSegment, type TranscriptionStatus, type UpdateWebhookParams, type UploadAudioParams, type UploadAudioResponse, type Usage, type UsageHistoryParams, type UsageHistoryRecord, type UsageHistoryResponse, type UsagePeriod, VeroAPIError, VeroTranscribe, type VeroTranscribeConfig, type Webhook, type WebhookDelivery, type WebhookEvent, type WordTimestamp, createWebhookVerifier, VeroTranscribe as default };