whisperai-sdk 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# whisperai-sdk
+
+Unofficial TypeScript SDK for [WhisperAI](https://whisperai.com/). This package provides methods and interfaces for interacting with the WhisperAI service without external runtime dependencies (except axios).
+
+**Disclaimer:** This is an unofficial implementation and is not affiliated with WhisperAI.
+
+## Installation
+
+```bash
+npm install whisperai-sdk
+```
+
+## Usage
+
+### Initialization
+
+Initialize the client with your WhisperAI credentials.
+
+```typescript
+import { WhisperClient } from 'whisperai-sdk';
+
+const client = new WhisperClient({
+  login: {
+    email: "your-email@example.com",
+    password: "your-password"
+  },
+  // Optional: Override default settings
+  // whisperUrl: "https://whisperai.com",
+  // chunkSize: 8 * 1024 * 1024 // 8MB
+});
+```
+
+The client handles authentication automatically. It will log in on the first request and refresh the session if the token expires.
+
+### Methods
+
+#### User & Account
+
+Get current user information, usage statistics, and subscription details.
+
+```typescript
+// Get user info
+const userInfo = await client.user();
+console.log(`User: ${userInfo.firstName} ${userInfo.lastName}`);
+
+// Get usage stats
+const usage = await client.usage();
+console.log(`Monthly Usage: ${usage.monthlyUsageMinutes} minutes`);
+
+// Get subscription details
+const subscription = await client.subscriptionDetails();
+```
+
+#### Uploading Audio
+
+Upload audio files for transcription. The `upload` method handles file chunking automatically.
+
+```typescript
+import fs from 'fs';
+
+// Read file buffer
+const buffer = fs.readFileSync('./interview.mp3');
+
+// Upload
+const result = await client.upload(buffer, {
+  filename: 'interview.mp3',
+  durationSeconds: 120, // Total duration in seconds
+  mimeType: 'audio/mpeg', // Optional
+  title: 'Interview with John Doe', // Optional
+  enableSpeakerDetection: true, // Optional
+  speakerCount: 'auto' // Optional: 'auto' or number
+});
+
+console.log(`Uploaded recording ID: ${result.id}`);
+```
+
+#### Transcription
+
+Manage transcriptions for uploaded recordings.
+
+```typescript
+const recordingId = 12345;
+
+// Start/Request transcription
+const transcriptionJob = await client.transcription(recordingId);
+
+// Check recording status and get transcription result
+const recording = await client.recording(recordingId);
+
+if (recording.status === 'completed' && recording.transcription) {
+  console.log(recording.transcription.content);
+  
+  // Access segments with timestamps
+  recording.transcription.segments.forEach(segment => {
+    console.log(`[${segment.start} - ${segment.end}]: ${segment.text}`);
+  });
+}
+```
+
+#### Translation
+
+Translate a recording to another language.
+
+```typescript
+const recordingId = 12345;
+
+// Translate to Spanish
+const translation = await client.translate(recordingId, 'es');
+```
+
+#### Recordings Management
+
+List and retrieve recordings.
+
+```typescript
+// Get a specific recording by ID
+const recording = await client.recording(recordingId);
+
+// List recordings (paginated)
+const recordingsList = await client.recordings({
+  limit: 10,
+  page: 1,
+  // search: "interview", // Optional search query
+  // status: "completed"  // Optional status filter
+});
+
+console.log(`Found ${recordingsList.meta.totalItems} recordings`);
+```
+
+#### Analytics
+
+Get a summary of your activity.
+
+```typescript
+const summary = await client.summary();
+console.log(`Total recordings: ${summary.recordings.total}`);
+```
+
+## Error Handling
+
+The SDK throws specific errors for different failure scenarios.
+
+```typescript
+import { WhisperAuthError, WhisperNetworkError, WhisperApiError } from 'whisperai-sdk/errors';
+
+try {
+  await client.user();
+} catch (error) {
+  if (error instanceof WhisperAuthError) {
+    console.error("Authentication failed. Check credentials.");
+  } else if (error instanceof WhisperNetworkError) {
+    console.error("Network issue.");
+  } else if (error instanceof WhisperApiError) {
+    console.error(`API Error ${error.status}: ${JSON.stringify(error.data)}`);
+  } else {
+    console.error("Unknown error:", error);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import type { ClientOptions, UserInfo, UsageInfo, InitMetaFile, InitChunkResponse, UploadChunkResponse, FinalizeChunkResponse, TranscriptionResponse, TranslateResponse, SummaryResponse, RecordingResponse, RecordingsQuery, RecordingsResponse, SubscriptionDetailsResponse } from "./types.js";
+export declare class WhisperClient {
+    private cookies?;
+    private readonly clientOptions;
+    constructor(clientOptions: ClientOptions);
+    login(): Promise<UserInfo>;
+    user(): Promise<UserInfo>;
+    usage(): Promise<UsageInfo>;
+    subscriptionDetails(): Promise<SubscriptionDetailsResponse>;
+    upload(fileBuffer: Uint8Array, meta: InitMetaFile): Promise<FinalizeChunkResponse>;
+    initChunk(fileBuffer: Uint8Array, meta: InitMetaFile): Promise<InitChunkResponse>;
+    uploadChunk(fileBuffer: Uint8Array, recordingId: number, chunkIndex: number): Promise<UploadChunkResponse>;
+    finalizeChunk(recordingId: number): Promise<FinalizeChunkResponse>;
+    transcription(recordingId: number): Promise<TranscriptionResponse>;
+    translate(recordingId: number, language: string): Promise<TranslateResponse>;
+    recording(recordingId: number): Promise<RecordingResponse>;
+    recordings(query?: RecordingsQuery): Promise<RecordingsResponse>;
+    summary(): Promise<SummaryResponse>;
+    private get loginLink();
+    private get userLink();
+    private get usageLink();
+    private get subscriptionDetailsLink();
+    private get initChunkLink();
+    private get uploadChunkLink();
+    private get finalizeChunkLink();
+    private get transcriptionLink();
+    private get summaryLink();
+    private translateLink;
+    private recordingLink;
+    private get recordingsLink();
+    private getCountChunks;
+    private get requestOptions();
+    private recall;
+    private handleRequest;
+}

package/dist/constant.d.ts

@@ -0,0 +1,9 @@
+export declare enum WhisperStatus {
+    PENDING = "pending",
+    VALIDATING = "validating",
+    UPLOADING = "uploading",
+    PROCESSING = "processing",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    CANCELLED = "cancelled"
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export declare abstract class WhisperError extends Error {
+    abstract readonly code: string;
+    protected constructor(message: string);
+}
+export declare class WhisperApiError extends WhisperError {
+    readonly status: number;
+    readonly response: unknown;
+    readonly code = "API_ERROR";
+    constructor(status: number, response: unknown);
+}
+export declare class WhisperAuthError extends WhisperError {
+    readonly code = "AUTH_ERROR";
+    constructor();
+}
+export declare class WhisperNetworkError extends WhisperError {
+    readonly code = "NETWORK_ERROR";
+    constructor(cause?: unknown);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./client.js";
+export * from "./constant.js";

package/dist/index.js

@@ -0,0 +1,203 @@
+// src/client.ts
+import axios from "axios";
+
+// src/errors.ts
+class WhisperError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+class WhisperApiError extends WhisperError {
+  status;
+  response;
+  code = "API_ERROR";
+  constructor(status, response) {
+    super(`Whisper API error (${status})`);
+    this.status = status;
+    this.response = response;
+  }
+}
+
+class WhisperAuthError extends WhisperError {
+  code = "AUTH_ERROR";
+  constructor() {
+    super("Authentication failed");
+  }
+}
+
+class WhisperNetworkError extends WhisperError {
+  code = "NETWORK_ERROR";
+  constructor(cause) {
+    super("Network error");
+    this.cause = cause;
+  }
+}
+
+// src/client.ts
+class WhisperClient {
+  cookies;
+  clientOptions;
+  constructor(clientOptions) {
+    this.clientOptions = {
+      whisperUrl: "https://whisperai.com",
+      chunkSize: 8 * 1024 * 1024,
+      ...clientOptions
+    };
+  }
+  login() {
+    return this.handleRequest(axios.post(this.loginLink, this.clientOptions.login));
+  }
+  user() {
+    return this.recall(() => axios.get(this.userLink, this.requestOptions));
+  }
+  usage() {
+    return this.recall(() => axios.get(this.usageLink, this.requestOptions));
+  }
+  subscriptionDetails() {
+    return this.recall(() => axios.get(this.subscriptionDetailsLink, this.requestOptions));
+  }
+  upload(fileBuffer, meta) {
+    const totalChunks = this.getCountChunks(fileBuffer.length);
+    return this.initChunk(fileBuffer, meta).then((response) => Promise.all(Array.from({ length: totalChunks }, (_, i) => this.uploadChunk(fileBuffer, response.recordingId, i))).then(() => this.finalizeChunk(response.recordingId)));
+  }
+  initChunk(fileBuffer, meta) {
+    return this.recall(() => axios.post(this.initChunkLink, {
+      filename: meta.filename,
+      durationSeconds: meta.durationSeconds,
+      totalSize: fileBuffer.length,
+      mimeType: meta.mimeType ?? "",
+      title: meta.title ?? meta.filename,
+      enableSpeakerDetection: meta.enableSpeakerDetection ?? false,
+      speakerCount: meta.speakerCount ?? "auto",
+      language: meta.language ?? "",
+      totalChunks: this.getCountChunks(fileBuffer.length)
+    }, this.requestOptions));
+  }
+  uploadChunk(fileBuffer, recordingId, chunkIndex) {
+    const start = chunkIndex * this.clientOptions.chunkSize;
+    const end = Math.min(start + this.clientOptions.chunkSize, fileBuffer.length);
+    const chunk = fileBuffer.slice(start, end);
+    const blob = new Blob([chunk], { type: "application/octet-stream" });
+    const formData = new FormData;
+    formData.append("chunk", blob, `chunk_${chunkIndex}`);
+    formData.append("recordingId", recordingId.toString());
+    formData.append("chunkIndex", chunkIndex.toString());
+    return this.recall(() => axios.post(this.uploadChunkLink, formData, this.requestOptions));
+  }
+  finalizeChunk(recordingId) {
+    return this.recall(() => axios.post(this.finalizeChunkLink, { recordingId }, this.requestOptions));
+  }
+  transcription(recordingId) {
+    return this.recall(() => axios.post(this.transcriptionLink, { recordingId }, this.requestOptions));
+  }
+  translate(recordingId, language) {
+    return this.recall(() => axios.post(this.translateLink(recordingId), { targetLanguage: language }, this.requestOptions));
+  }
+  recording(recordingId) {
+    return this.recall(() => axios.get(this.recordingLink(recordingId), this.requestOptions));
+  }
+  recordings(query) {
+    return this.recall(() => axios.get(this.recordingsLink, {
+      ...this.requestOptions,
+      params: { page: 1, limit: 5, ...query ?? {} }
+    }));
+  }
+  summary() {
+    return this.recall(() => axios.get(this.summaryLink, this.requestOptions));
+  }
+  get loginLink() {
+    return `${this.clientOptions.whisperUrl}/api/login`;
+  }
+  get userLink() {
+    return `${this.clientOptions.whisperUrl}/api/user`;
+  }
+  get usageLink() {
+    return `${this.clientOptions.whisperUrl}/api/usage`;
+  }
+  get subscriptionDetailsLink() {
+    return `${this.clientOptions.whisperUrl}/api/subscription-details`;
+  }
+  get initChunkLink() {
+    return `${this.clientOptions.whisperUrl}/api/v2/recordings/chunked/init`;
+  }
+  get uploadChunkLink() {
+    return `${this.clientOptions.whisperUrl}/api/v2/recordings/chunked/upload`;
+  }
+  get finalizeChunkLink() {
+    return `${this.clientOptions.whisperUrl}/api/v2/recordings/chunked/finalize`;
+  }
+  get transcriptionLink() {
+    return `${this.clientOptions.whisperUrl}/api/v2/transcription`;
+  }
+  get summaryLink() {
+    return `${this.clientOptions.whisperUrl}/api/analytics/summary`;
+  }
+  translateLink(recordingId) {
+    return `${this.clientOptions.whisperUrl}/api/v2/translation/${recordingId}/translate`;
+  }
+  recordingLink(recordingId) {
+    return `${this.clientOptions.whisperUrl}/api/recordings/${recordingId}`;
+  }
+  get recordingsLink() {
+    return `${this.clientOptions.whisperUrl}/api/recordings-paginated`;
+  }
+  getCountChunks(size) {
+    return Math.ceil(size / this.clientOptions.chunkSize);
+  }
+  get requestOptions() {
+    return {
+      headers: {
+        Cookie: this.cookies
+      }
+    };
+  }
+  async recall(call) {
+    try {
+      if (typeof this.cookies !== "string")
+        await this.login();
+      return await this.handleRequest(call());
+    } catch (error) {
+      if (error.code !== "AUTH_ERROR") {
+        throw error;
+      }
+      await this.login();
+      return this.handleRequest(call());
+    }
+  }
+  async handleRequest(request) {
+    try {
+      const response = await request;
+      this.cookies = (response.headers["set-cookie"] ?? []).join("; ");
+      return response.data;
+    } catch (err) {
+      console.log("err", err);
+      if (axios.isAxiosError(err)) {
+        if (!err.response) {
+          throw new WhisperNetworkError(err);
+        }
+        if (err.response.status === 401) {
+          throw new WhisperAuthError;
+        }
+        throw new WhisperApiError(err.response.status, err.response.data);
+      }
+      throw err;
+    }
+  }
+}
+// src/constant.ts
+var WhisperStatus;
+((WhisperStatus2) => {
+  WhisperStatus2["PENDING"] = "pending";
+  WhisperStatus2["VALIDATING"] = "validating";
+  WhisperStatus2["UPLOADING"] = "uploading";
+  WhisperStatus2["PROCESSING"] = "processing";
+  WhisperStatus2["COMPLETED"] = "completed";
+  WhisperStatus2["FAILED"] = "failed";
+  WhisperStatus2["CANCELLED"] = "cancelled";
+})(WhisperStatus ||= {});
+export {
+  WhisperStatus,
+  WhisperClient
+};

package/dist/types.d.ts

@@ -0,0 +1,218 @@
+import { WhisperStatus } from "./constant.js";
+export interface ClientOptions {
+    login: {
+        email: string;
+        password: string;
+    };
+    chunkSize?: number;
+    whisperUrl?: string;
+}
+export interface RequestError {
+    message: string;
+    path: string;
+}
+export interface UserInfo {
+    id: number;
+    username: string | null;
+    email: string;
+    firstName: string;
+    lastName: string;
+    profileImageUrl: string | null;
+    subscriptionTier: "free" | "premium";
+    stripeSubscriptionId: string | null;
+    stripeCustomerId: string | null;
+    trialStartDate: string | null;
+    trialEndDate: string | null;
+    hasUsedTrial: boolean;
+    monthlyUsageMinutes: number;
+    usageResetDate: string;
+    deletedMinutesThisCycle: number;
+    subscriptionStatus: "past_due" | "active";
+    subscriptionEndDate: string | null;
+    cancellationOffered: boolean;
+    unsubscribed: boolean;
+    hearAboutUs: string | null;
+    industry: "Healthcare & Medical" | "Legal & Compliance" | "Education & Research" | "Media & Entertainment" | "Technology & Software" | "Consulting & Professional Services" | "Financial Services (Banking, Insurance, Accounting)" | "Government & Nonprofit" | "Sales & Marketing / Advertising" | "Real Estate & Construction" | "Manufacturing & Engineering" | "Human Resources & Recruiting" | "Customer Support / Call Centers" | "Student" | string;
+    totalMinutes: number;
+    recordingsCount: number;
+    subscriptionPausedUntil: string | null;
+    subscriptionPauseStarts: string | null;
+    subscriptionOriginalTier: string | null;
+    discountCodeApplied: string | null;
+    retentionOfferShown: string | null;
+    billingFrequency: "monthly" | "weekly";
+    hasSeenTutorial: boolean;
+    lastLoginAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface UsageInfo {
+    monthlyUsageMinutes: number;
+    subscriptionTier: "free" | "premium";
+    limits: {
+        monthlyMinutes: number;
+        dailyMinutes: number;
+        maxFileSize: number;
+    };
+}
+export interface InitMetaFile {
+    filename: string;
+    durationSeconds: number;
+    title?: string;
+    mimeType?: string;
+    totalSize?: number;
+    language?: number;
+    enableSpeakerDetection?: boolean;
+    speakerCount?: "auto" | number;
+}
+export interface InitChunkResponse {
+    sessionId: string;
+    recordingId: number;
+}
+export interface UploadChunkResponse {
+    success: boolean;
+    chunkIndex: number;
+    uploadedChunks: number;
+    totalChunks: number;
+}
+export interface FinalizeChunkResponse {
+    id: number;
+    userId: number;
+    title: string;
+    originalFilename: string;
+    fileExtension: string;
+    mimeType: string;
+    audioUrl: string;
+    duration: number;
+    language: string;
+    status: WhisperStatus;
+    speakerDetectionEnabled: boolean;
+    speakerCount: number | null;
+    totalChunks: number;
+    metadata: Record<string, unknown> | null;
+    idempotencyKey: string | null;
+    uploadSessionId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TranscriptionResponse {
+    id: number;
+    recordingId: number;
+    status: "queued" | "processing" | "completed" | "failed" | "canceled";
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TranslateResponse {
+    success: true;
+    message: string;
+    translation: {
+        id: number;
+        transcriptionId: number;
+        targetLanguage: string;
+        content: string;
+        status: string;
+    };
+}
+export interface SummaryResponse {
+    usage: {
+        monthlyMinutes: number;
+        monthlyLimit: number;
+        percentage: number;
+    };
+    recordings: {
+        total: number;
+        thisMonth: number;
+        totalMinutes: number;
+        averageDuration: number;
+    };
+    activity: {
+        dailyCounts: Record<string, number>;
+        mostActiveDay: string;
+        currentStreak: number;
+    };
+    insights: {
+        shouldUpgrade: boolean;
+        suggestedTier: string;
+        upgradeReason: string;
+    };
+}
+export interface RecordingResponse {
+    id: number;
+    userId: number;
+    title: string;
+    originalFilename: string;
+    fileExtension: string;
+    mimeType: string;
+    audioUrl: string;
+    duration: number;
+    language: string;
+    status: string;
+    speakerDetectionEnabled: boolean;
+    speakerCount: number | null;
+    totalChunks: number;
+    metadata: Record<string, unknown> | null;
+    idempotencyKey: string | null;
+    uploadSessionId: string;
+    accessToken: string;
+    accessTokenExpiry: string;
+    createdAt: string;
+    updatedAt: string;
+    transcription: {
+        id: number;
+        userId: number;
+        recordingId: number;
+        content: string;
+        editedContent: string | null;
+        confidence: number;
+        segments: Array<{
+            id: number;
+            start: number;
+            end: number;
+            text: string;
+        }>;
+        translations: Array<{
+            id: number;
+            transcriptionId: number;
+            targetLanguage: string;
+            content: string;
+            status: string;
+            createdAt: string;
+        }>;
+        timestamps: {
+            words: unknown[];
+            duration: number;
+            language: string;
+            segments: Array<{
+                id: number;
+                start: number;
+                end: number;
+                text: string;
+            }>;
+        };
+        speakers: unknown | null;
+        speakerNames: Record<string, unknown>;
+        createdAt: string;
+        updatedAt: string;
+        summary: unknown | null;
+    };
+}
+export interface RecordingsQuery {
+    page?: number;
+    limit?: number;
+}
+export interface RecordingsResponse {
+    data: RecordingResponse[];
+    total: string;
+    page: number;
+    limit: number;
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+export interface SubscriptionDetailsResponse {
+    isPaidPlan: boolean;
+    isTrialActive: boolean;
+    nextBillingDate: string | null;
+    billingAmount: number | null;
+    subscriptionStatus: string;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "whisperai-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for WhisperAI: methods and interfaces for interacting with the service without external runtime dependencies.",
+  "keywords": [
+    "whisper",
+    "speech-to-text",
+    "transcription",
+    "typescript",
+    "sdk"
+  ],
+  "homepage": "https://whisperai.com/",
+  "bugs": {
+    "url": "https://github.com/iHaiduk/whisperai/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iHaiduk/whisperai.git"
+  },
+  "license": "MIT",
+  "author": "Igor Haiduk",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run clean && bun build ./src/index.ts --outdir ./dist --target=node --format=esm --external axios && tsc --emitDeclarationOnly",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "release": "semantic-release"
+  },
+  "dependencies": {
+    "axios": "^1.13.2"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "20.2.0",
+    "@commitlint/config-conventional": "20.2.0",
+    "@eslint/js": "9.39.2",
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/exec": "7.1.0",
+    "@semantic-release/git": "10.0.1",
+    "@semantic-release/github": "12.0.2",
+    "@semantic-release/npm": "13.1.3",
+    "@types/bun": "^1.3.5",
+    "@types/node": "25.0.3",
+    "@typescript-eslint/eslint-plugin": "8.50.1",
+    "@typescript-eslint/parser": "8.50.1",
+    "conventional-changelog-conventionalcommits": "9.1.0",
+    "eslint": "9.39.2",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.4",
+    "prettier": "3.7.4",
+    "semantic-release": "25.0.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.50.1"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "module": "./dist/index.js"
+}