@aceint/ai-interviews

Backend TypeScript SDK for Aceint AI interview session APIs.

This package is the higher-level SDK for clients who want to create Aceint-hosted interview sessions from their backend without manually managing Aceint access tokens for every request.

What This Package Handles

• issues the first Aceint access token internally
• reuses active tokens in memory by default
• refreshes tokens when needed
• retries one protected request after a 401
• calls Aceint session APIs from your backend

This package is intended for backend or server environments.

Do not install it in a browser-only frontend application.

Requirements

• Node.js >=18
• Aceint client credentials from the Aceint Credentials tab

Installation

npm install @aceint/ai-interviews

Public Modes

• dev -> https://dev.aceint.ai/backend/api/v1
• prod -> https://interview.aceint.ai/backend/api/v1

Use dev for development, QA, and integration testing.

Use prod for live production traffic.

Quick Start

import { SessionClient } from '@aceint/ai-interviews';

const interviews = new SessionClient({
  mode: 'dev',
  clientPublicId: process.env.ACEINT_CLIENT_PUBLIC_ID!,
  apiKey: process.env.ACEINT_API_KEY!,
  apiSecret: process.env.ACEINT_API_SECRET!,
  accessTtl: '15m',
});

const session = await interviews.createSession({
  userId: '62704ecf-9ef2-4915-ae04-bb79ef2b25a5',
  taskId: 'e8d9ba6c-6a9c-44e2-a3e9-257d7389a95f',
  sessionId: '3bcd6789-c679-4ff3-bdb1-e1730f3cb46b',
  fullName: 'Sample Candidate',
  jobRole: 'Java Developer',
  interviewCategory: 'Technical',
  interviewDomain: 'Product-based',
  duration: 30,
  interviewMode: 'BY_CLIENT',
  experience: '0-2',
  interviewDifficulty: 'Medium',
  sessionStatus: 'New',
  createdBy: 'Example Recruiter',
  topics: [
    {
      id: 'topic-1',
      name: 'JavaScript Fundamentals',
      weightage: 25,
      allocated_time: 3,
      knowledge_depth: 3,
      subtopics: [
        {
          id: 'subtopic-1',
          name: 'Variable Scoping and Hoisting',
          concepts: ['Function Scope', 'Temporal Dead Zone'],
        },
      ],
    },
  ],
});

console.log(session.sessionId);
console.log(session.iframeUrl);

createSession() is the primary session creation method and accepts the real session payload shape used by client backends.

Recommended Architecture

Use this package from your backend, then return only the values your frontend needs.

Recommended flow:

frontend -> your backend -> SessionClient -> Aceint

For Aceint-hosted interview embeds, your backend should create the session and return iframeUrl to the frontend for rendering.

API

new SessionClient(options)

Creates a backend client that manages Aceint auth internally for AI interview session APIs.

client.createSession(input)

Creates a session with the main Aceint session payload and returns normalized session data including:

• sessionId
• status
• token
• livekitUrl
• iframeUrl

client.createSessionRaw(payload)

Lower-level passthrough API kept for advanced compatibility cases.

client.getSession(sessionId)

Fetches the stored Aceint interview session data for a session ID.

client.getSessionRecord(sessionId)

Fetches normalized session record data including:

• sessionId
• videoLink
• audioLink
• transcript
• category
• subCategory

Token Management

This package uses @aceint/auth internally.

By default it keeps tokens in memory per SessionClient instance.

If you run multiple backend instances or want shared token state, provide a custom tokenStore.

When To Use @aceint/auth Instead

Use @aceint/auth directly when you only want low-level token issuance, refresh, and revoke control.

Use @aceint/ai-interviews when you want the Aceint AI interview session APIs and do not want to manually handle the token lifecycle in your backend code.