vp-sdk

The official Node.js SDK for the Scoreexl API—a secure audio AI platform providing Speech-to-Text (STT), Text-to-Speech (TTS) with Google Chirp3 HD & Deepgram Aura-2, RAG-based knowledge, analytics, credits, and notifications.

Features

• Complete API Coverage
• TypeScript Support
• Authentication Management
• Error Handling
• Modular Architecture
• File Upload Support
• Retry Logic
• Pagination Support

Installation

# npm
npm install @ageofai/vp-sdk

# yarn
yarn add @ageofai/vp-sdk

Quick Start

const { VpSdk } = require('@ageofai/vp-sdk');
(async () => {
  const client = new VpSdk({ apiKey: 'YOUR_API_KEY' });
  try {
    // Register & log in
    const user = await client.auth.register({ email: '[email protected]', password: 'StrongP@ssw0rd' });
    await client.auth.login({ email: user.email, password: 'StrongP@ssw0rd' });

    // List voices & synthesize text
    const voices = await client.tts.listVoices();
    const synth = await client.tts.synthesize({
      text: 'Hello, Scoreexl!',
      voiceId: voices[0].id
    });
    console.log('Synthesis started:', synth);
  } catch (error) {
    console.error('Quick start error:', error);
  }
})();

API Reference

Authentication

• register(userData)
  Register a new user.

  const user = await client.auth.register({ email, password });

• login(credentials)
  Log in and store tokens.

  await client.auth.login({ email, password });

• logout()
  Log out and clear tokens.

  await client.auth.logout();

Users

• getUser(userId)
  Fetch user details by ID.

  const user = await client.users.getUser(userId);

• updateUser(userId, data)
  Update user profile.

  await client.users.updateUser(userId, updateData);

• deleteUser(userId)
  Remove a user account.

  await client.users.deleteUser(userId);

Text-to-Speech (TTS)

• listVoices()
  Get available voices.

  const voices = await client.tts.listVoices();

• synthesize(options)
  Start a synthesis job.

  const { synthesisId } = await client.tts.synthesize({ text, voiceId });

• getSynthesisStatus(synthesisId)
  Check synthesis status.

  const status = await client.tts.getSynthesisStatus(synthesisId);

• downloadAudio(synthesisId)
  Download completed audio.

  const stream = await client.tts.downloadAudio(synthesisId);

Speech-to-Text (STT)

• transcribe(options)
  Submit an audio file for transcription.

  const { transcriptionId } = await client.stt.transcribe({ file: fsStream });

• getTranscriptionStatus(transcriptionId)
  Check transcription status.

  const result = await client.stt.getTranscriptionStatus(transcriptionId);

Credits

• getCredits()
  Retrieve current credit balance.

  const credits = await client.credits.getCredits();

• purchaseCredits(amount)
  Purchase additional credits.

  await client.credits.purchaseCredits(amount);

Analytics

• getUsageStats(params)
  Fetch usage analytics.

  const stats = await client.analytics.getUsageStats({ from, to });

Notifications

• listNotifications()
  Retrieve user notifications.

  const list = await client.notifications.listNotifications();

• markAsRead(notificationId)
  Mark a notification as read.

  await client.notifications.markAsRead(notificationId);

RAG

• createSession(context)
  Start a RAG session with context.

  const { sessionId } = await client.rag.createSession({ documents });

• query(sessionId, query)
  Query the RAG session.

  const response = await client.rag.query(sessionId, 'Your question');

API Keys

• listKeys()
  List all API keys.

  const keys = await client.apiKeys.listKeys();

• createKey(params)
  Generate a new API key.

  const key = await client.apiKeys.createKey({ name });

• revokeKey(keyId)
  Revoke an existing key.

  await client.apiKeys.revokeKey(keyId);

Agents

• listAgents()
  Fetch available agents.

  const agents = await client.agents.listAgents();

• runAgent(agentId, input)
  Execute an agent with input.

  const result = await client.agents.runAgent(agentId, { prompt });

Usage Tracking

• trackEvent(eventData)
  Record a custom event.

  await client.usage.trackEvent({ event, metadata });

• getEvents(params)
  Retrieve tracked events.

  const events = await client.usage.getEvents({ limit, offset });

Error Handling

All SDK errors extend a base ScoreexlError and include:

• message: human-readable error
• statusCode: HTTP status
• code: machine error code
• details: additional metadata

const {
  AuthenticationError,
  RateLimitError,
  TranscriptionError,
  SynthesisError
} = require('@ageofai/vp-sdk').errors;

try {
  await client.auth.login({ email, password });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message, error.statusCode, error.code);
  } else if (error instanceof RateLimitError) {
    console.error('Too many requests:', error.details);
  } else {
    console.error('Unexpected error:', error);
  }
}

Advanced Configuration

Custom Axios Configuration

const client = new VpSdk({
  apiKey: 'KEY',
  axiosConfig: { baseURL: 'https://api.scoreexl.com', timeout: 10000 }
});

Manual Token Management

client.setAccessToken('ACCESS_TOKEN');
client.setRefreshToken('REFRESH_TOKEN');

File Uploads

Node.js:

const fs = require('fs');
await client.stt.transcribe({ file: fs.createReadStream('audio.wav') });

Browser:

await client.stt.transcribe({ file: new File([blob], 'audio.wav') });

TypeScript Support

Full type definitions are included.

import { VpSdk, AuthClient } from '@ageofai/vp-sdk';
const client: VpSdk = new VpSdk({ apiKey: 'KEY' });

Examples

Complete TTS Workflow

const fs = require('fs');
(async () => {
  const client = new VpSdk({ apiKey: 'YOUR_API_KEY' });
  await client.auth.login({ email: '[email protected]', password: 'StrongP@ssw0rd' });

  const voices = await client.tts.listVoices();
  const { synthesisId } = await client.tts.synthesize({
    text: 'Hello, Scoreexl!',
    voiceId: voices[0].id
  });

  let status;
  do {
    await new Promise(r => setTimeout(r, 2000));
    status = await client.tts.getSynthesisStatus(synthesisId);
  } while (status.state !== 'completed');

  const audioStream = await client.tts.downloadAudio(synthesisId);
  const writeStream = fs.createWriteStream('output.mp3');
  audioStream.pipe(writeStream);
  console.log('Audio saved to output.mp3');
})();

STT Transcription with Error Handling

const fs = require('fs');
const { TranscriptionError } = require('@ageofai/vp-sdk').errors;

(async () => {
  const client = new VpSdk({ apiKey: 'YOUR_API_KEY' });
  try {
    await client.auth.login({ email: '[email protected]', password: 'StrongP@ssw0rd' });
    const fileStream = fs.createReadStream('input.wav');
    const { transcriptionId } = await client.stt.transcribe({ file: fileStream });

    let result;
    do {
      await new Promise(r => setTimeout(r, 2000));
      result = await client.stt.getTranscriptionStatus(transcriptionId);
    } while (result.state !== 'completed');

    console.log('Transcribed text:', result.text);
    console.table(result.segments);
  } catch (error) {
    if (error instanceof TranscriptionError) {
      console.error('Transcription failed:', error.details);
    } else {
      throw error;
    }
  }
})();

Contributing

See CONTRIBUTING.md for guidelines.

Support

Open an issue in this repository