@akapulu/server

Server-side API client for Akapulu conversation endpoints.

What this package contains

• createAkapuluServerClient() for backend use
• connectConversation() request helper
• pollConversationUpdates() request helper
• getConversationDetail() request helper
• getConversationRecording() request helper
• Typed request/response interfaces

Install

npm install @akapulu/server

Usage

import { createAkapuluServerClient } from "@akapulu/server";

const akapulu = createAkapuluServerClient();

const connect = await akapulu.connectConversation({
  scenario_id: "YOUR_SCENARIO_ID",
  avatar_id: "YOUR_AVATAR_ID",
});

const detail = await akapulu.getConversationDetail("YOUR_CONVERSATION_SESSION_ID");

const recording = await akapulu.getConversationRecording("YOUR_CONVERSATION_SESSION_ID");

Set AKAPULU_API_KEY on your server runtime before using this package. AKAPULU_API_BASE_URL is optional and defaults to https://akapulu.com/api.

Additional methods

getConversationDetail(conversationSessionId) returns:

type ConversationDetailResponse = {
  id: string;
  created_at: string;
  created_at_text: string;
  duration_text: string;
  avatar: {
    id: string;
    href: string;
    profile_image_url: string;
  };
  scenario_id: string;
  recording: {
    has_recording: boolean;
    status_text: string;
    is_ready: boolean;
  };
  transcript_rows: Array<{
    role: string;
    content?: string;
    node_id?: string;
    tool_call_id?: string;
    tool_calls?: unknown[];
  }>;
};

getConversationRecording(conversationSessionId) returns:

type ConversationRecordingResponse =
  | {
      kind: "redirect";
      status: number;
      location: string;
    }
  | {
      kind: "json";
      status: number;
      payload: unknown;
    }
  | {
      kind: "binary";
      status: number;
      body: ArrayBuffer;
      contentType: string;
      contentDisposition: string;
    };