StudyFetch SDK

A JavaScript/TypeScript SDK for interacting with the StudyFetch API, enabling easy integration of AI-powered educational components into your applications.

Installation

npm install studyfetch-sdk

Quick Start

import StudyFetchAPI from 'studyfetch-sdk';
// or for CommonJS
const { StudyFetchAPI } = require('studyfetch-sdk');

// Initialize the SDK
const studyfetch = new StudyFetchAPI({
  apiKey: 'your-api-key',
  baseURL: 'https://api.studyfetch.com/api/v1' // optional, defaults to localhost
});

Features

• 📚 Material Management - Upload and manage educational content
• 💬 AI Chat Components - Create intelligent chat interfaces
• 🎯 Multiple Component Types - Flashcards, explainers, tests, scenarios, and audio recaps
• 📊 Usage Tracking - Monitor usage statistics and analytics
• 🔗 Embeddable Components - Generate embed codes for seamless integration

API Reference

Initialization

const studyfetch = new StudyFetchAPI({
  apiKey: 'your-api-key',        // Required
  baseURL: 'https://...'         // Optional, defaults to http://localhost:3001/api/v1
});

Materials

Create Material

const material = await studyfetch.createMaterial({
  name: 'Chapter 1: Introduction',
  content: {
    type: 'text',
    text: 'Your educational content here...'
  }
});

Get All Materials

const materials = await studyfetch.getMaterials();

Delete Material

await studyfetch.deleteMaterial(materialId);

Components

Create Chat Component

const chatComponent = await studyfetch.createChatComponent({
  name: 'Biology Tutor',
  model: 'openai:gpt-4',  // optional, defaults to 'openai:gpt-4.1'
  materials: [materialId1, materialId2],  // optional
  config: {
    // additional configuration
  }
});

Create Other Components

// Flashcards
const flashcards = await studyfetch.createFlashcardsComponent({
  name: 'Biology Flashcards',
  config: { /* options */ }
});

// Explainers
const explainers = await studyfetch.createExplainersComponent({
  name: 'Concept Explainer',
  config: { /* options */ }
});

// Practice Tests
const tests = await studyfetch.createTestsComponent({
  name: 'Chapter Quiz',
  config: { /* options */ }
});

// Scenarios
const scenarios = await studyfetch.createScenariosComponent({
  name: 'Clinical Scenarios',
  config: { /* options */ }
});

// Audio Recaps
const audioRecap = await studyfetch.createAudioRecapComponent({
  name: 'Lecture Summary',
  config: { /* options */ }
});

Get Components

// Get all components
const allComponents = await studyfetch.getComponents();

// Get components by type
const chatComponents = await studyfetch.getComponents('chat');
const flashcardComponents = await studyfetch.getComponents('flashcards');

Delete Component

await studyfetch.deleteComponent(componentId);

Component Interaction

Send Message to Chat Component

const response = await studyfetch.interactWithComponent(componentId, {
  message: 'Explain photosynthesis',
  userId: 'user123',     // optional
  groupId: 'class-a'     // optional
});

Embedding Components

Generate Embed Code

const embedData = await studyfetch.generateComponentEmbed(componentId, {
  userId: 'user123',
  groupId: 'class-a',
  sessionId: 'session123',
  width: '100%',
  height: '600px',
  expiryHours: 24,
  features: {
    enableWebSearch: true,
    enableHistory: true,
    enableVoice: true,
    enableFollowUps: true,
    placeholderText: 'Ask me anything...'
  }
});

console.log(embedData.embedUrl);  // URL to embed in iframe

Usage Tracking & Analytics

Get Usage Events

const usage = await studyfetch.getUsageEvents({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  eventType: 'chat_message',
  userId: 'user123',
  groupId: 'class-a',
  limit: 100,
  offset: 0
});

Get Usage Summary

const summary = await studyfetch.getUsageSummary({
  period: 'daily',  // 'hourly', 'daily', or 'monthly'
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  groupBy: 'user'   // 'user', 'group', 'model', or 'endpoint'
});

Get Usage Statistics

const stats = await studyfetch.getUsageStats({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  userId: 'user123',
  groupId: 'class-a'
});

Track Custom Events

await studyfetch.trackUsage({
  eventType: 'quiz_completed',
  userId: 'user123',
  groupId: 'class-a',
  resourceId: 'quiz123',
  metadata: {
    score: 85,
    duration: 300
  }
});

Analytics Helpers

// Get top users by usage
const topUsers = await studyfetch.getTopUsers({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  limit: 10
});

// Get top groups by usage
const topGroups = await studyfetch.getTopGroups({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  limit: 10
});

// Get token usage by model
const tokenUsage = await studyfetch.getTokenUsageByModel({
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Working with Chat Components

The SDK provides a ChatComponent class with additional methods:

// Create a chat component
const chatComponent = await studyfetch.createChatComponent({
  name: 'Math Tutor',
  materials: [materialId]
});

// Get iframe URL for embedding
const iframeUrl = await chatComponent.getIframeUrl({
  userId: 'user123',
  groupId: 'class-a',
  width: '100%',
  height: '600px',
  features: {
    enableWebSearch: true,
    enableVoice: true
  }
}, studyfetch);  // Pass the API instance

// Send a message directly
const response = await chatComponent.sendMessage(
  'What is the quadratic formula?',
  {
    userId: 'user123',
    groupId: 'class-a'
  }
);

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import StudyFetchAPI, {
  StudyFetchOptions,
  Material,
  ComponentResponse,
  EmbedOptions,
  EmbedResponse
} from 'studyfetch-sdk';

const options: StudyFetchOptions = {
  apiKey: 'your-api-key'
};

const studyfetch = new StudyFetchAPI(options);

Error Handling

The SDK throws errors for failed requests. Always wrap API calls in try-catch blocks:

try {
  const material = await studyfetch.createMaterial({
    name: 'Test Material',
    content: 'Content'
  });
} catch (error) {
  console.error('Failed to create material:', error.message);
}

Environment Variables

For security, store your API key in environment variables:

const studyfetch = new StudyFetchAPI({
  apiKey: process.env.STUDYFETCH_API_KEY
});

Examples

Complete Example: Creating a Study Session

// 1. Upload study material
const material = await studyfetch.createMaterial({
  name: 'Biology Chapter 1',
  content: {
    type: 'text',
    text: 'Photosynthesis is the process by which plants...'
  }
});

// 2. Create a chat component
const chatComponent = await studyfetch.createChatComponent({
  name: 'Biology Study Assistant',
  materials: [material.id]
});

// 3. Generate embed code
const embedData = await studyfetch.generateComponentEmbed(chatComponent.id, {
  userId: 'student123',
  features: {
    enableWebSearch: true,
    enableVoice: true
  }
});

// 4. Track usage
await studyfetch.trackUsage({
  eventType: 'study_session_started',
  userId: 'student123',
  resourceId: chatComponent.id
});

// 5. Get analytics
const stats = await studyfetch.getUsageStats({
  userId: 'student123'
});

Support

For issues, questions, or contributions, please visit our GitHub repository.

License

MIT