Skip to content

Forra JavaScript API SDK

A comprehensive TypeScript/JavaScript client library for the Forra API, providing seamless integration with authentication, real-time chat streaming, and all Forra platform features.

Installation

bun install @mirego/forra-api

Getting Started

1. Configure Token Management

First, set up token management for your platform. The SDK requires you to provide token storage methods:

import { setTokenManager } from "@mirego/forra-api";

setTokenManager({
  getAccessToken: async () => "YOUR_AUTH_TOKEN",
  getRefreshToken: async () => "",
  setAccessToken: () => {},
  setRefreshToken: () => {},
  removeAllTokens: () => {},
});

Examples

Chat Completion

import { chatCompletion } from "@mirego/forra-api";

// Stateless chat completion (no conversation context)
const response = await chatCompletion({
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is the capital of France?" },
  ],
  model: "gpt-4",
  assistant_id: "assistant-id",
});

console.log(response.messages);

API Reference: chatCompletion

For real-time streaming chunks, use streamStatelessChatCompletion.

Working with Files

import { uploadFile, getSignedUploadUrl } from "@mirego/forra-api";

// Upload a file
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const uploadResponse = await uploadFile({
  file: file,
  conversation_id: "conversation-id",
});

// Get signed URL for secure file access
const signedUrl = await getSignedUploadUrl({
  filename: "document.pdf",
  content_type: "application/pdf",
});

Discovering More Functions

For a complete reference of all available functions, types, and interfaces, see the Forra API Reference.

Best Practices

  1. Always handle errors: API calls can fail due to network issues, authentication problems, or rate limits.

  2. Use AbortController for streams: Implement proper cleanup for streaming operations.

  3. Implement token refresh logic: The SDK handles this automatically, but ensure your token manager is properly configured.

  4. Cache frequently accessed data: Consider caching assistant lists, configuration, etc.

  5. Use TypeScript: Take advantage of the comprehensive type definitions for better development experience.