StudyFetch API Platform

An API platform for publisher content integration, enabling AI-powered chatbots and study tools for educational publishers.

🚀 Quick Start

Prerequisites

• Node.js (v16 or later)
• MongoDB (local or cloud instance)
• npm or yarn

Installation

1. Clone and setup:

git clone <repository-url>
cd studyfetch-api
npm install

2. Environment Setup:

cd backend
cp env.example .env
# Edit .env with your MongoDB connection string and EMBED_APP_URL

⚠️ Security Requirements: Before starting, you must set up secure secrets. Generate them using:

cd backend
node scripts/generate-secrets.js

Then add the generated secrets to your .env file:

• JWT_SECRET - For user authentication tokens (minimum 64 characters)
• EMBED_SECRET - For embed tokens (minimum 32 characters)

Never use default or weak secrets in production!

3. Start Development Server:

# From root directory
npm run dev

# Also start the embed app for React embeds
cd embed-app
npm run dev  # Runs on port 3002

This will start backend (port 3001), dashboard (port 3000), and embed app (port 3002).

📚 API Usage

1. Create an Organization

First, create an organization to get API keys:

curl -X POST http://localhost:3001/api/v1/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wiley Publishing",
    "slug": "wiley",
    "email": "[email protected]"
  }'

2. Use the StudyFetch API

// Initialize the API client (conceptual - you'll use HTTP requests)
const Sfapi = new StudyFetchAPI({
    apikey: "sf_your_api_key_here" // Get from organization creation
})

// Create material from text
const material = await Sfapi.createMaterial({
    name: "Material 1", 
    content: {
        type: "text",
        text: "This is a test text about quantum physics..."
    }
})

// Create material from PDF
const materialFromPdf = await Sfapi.createMaterial({
    name: "Physics Textbook", 
    content: {
        type: "pdf",
        url: "https://example.com/textbook.pdf"
    }
})

const materialId = material.id;

// Create chat component
const chatComponent = await studyFetchApi.createChatComponent({
  name: 'Biology Tutor',
  model: "openai:gpt-4.1",
  materials: materialIds,
  config: {
    systemPrompt: 'You are a helpful biology tutor.',
    temperature: 0.7,
    maxTokens: 2000,
    enableWebSearch: true,
    enableRAGSearch: true
  }
});

// Generate embed token and URL
const embedData = await Sfapi.generateComponentEmbed(chatComponent.componentId, {
    userId: "student-123",
    groupId: "class-456"
});

console.log(embedData.embedUrl);
// Output: http://localhost:3002/embed/chat_abc123?token=...

3. Embed in Your Site

<iframe 
    src="http://localhost:3002/embed/chat_abc123?token=YOUR_TOKEN"
    width="100%" 
    height="600px"
    style="border: none; border-radius: 8px;"
    title="Physics Study Assistant">
</iframe>

The React embed app provides a modern, responsive interface that adapts to your site's theme.

🔑 API Endpoints

Materials

• POST /api/v1/materials - Create material from text
• POST /api/v1/materials/upload - Upload file (PDF, TXT, DOC)
• GET /api/v1/materials - List materials
• GET /api/v1/materials/:id - Get material details
• DELETE /api/v1/materials/:id - Delete material

Components (Chat, Flashcards, etc.)

• POST /api/v1/components - Create component
• GET /api/v1/components - List components
• GET /api/v1/components/:id - Get component details
• DELETE /api/v1/components/:id - Delete component
• POST /api/v1/components/:id/embed - Generate embed token

Embedding

• GET /api/v1/embed/:componentId - Redirects to React embed app
• POST /api/v1/embed/component/:componentId/interact - Component interactions

Organization Management

• POST /api/v1/organizations - Create organization
• GET /api/v1/organizations/profile - Get organization profile
• POST /api/v1/organizations/api-keys - Generate new API key
• GET /api/v1/organizations/api-keys - List API keys
• GET /api/v1/organizations/usage - Get usage statistics

SSO (Single Sign-On)

• POST /api/v1/sso/config - Configure SSO
• GET /api/v1/sso/config - Get SSO configuration
• POST /api/v1/sso/authenticate/:organizationId - Authenticate via SSO
• GET /api/v1/sso/session/:sessionId - Validate session
• GET /api/v1/sso/sessions - List active sessions

Usage Tracking & Analytics

• GET /api/v1/usage/events - Get detailed usage events
• GET /api/v1/usage/summary - Get aggregated usage summaries
• GET /api/v1/usage/stats - Get usage statistics
• GET /api/v1/usage/billing - Get billing information
• POST /api/v1/usage/track - Track custom events

📊 Usage Tracking

The platform provides comprehensive usage tracking and analytics:

1. Automatic Event Tracking - All API operations, chat interactions, and resource operations are tracked
2. Token Usage & Costs - Real-time tracking of AI model token consumption with automatic cost calculation
3. User & Group Analytics - Analyze usage patterns by user and group for detailed insights
4. Billing Reports - Generate detailed billing information with cost breakdowns by model, user, and time period
5. Custom Events - Track custom events specific to your application needs

Example: Get usage statistics

const stats = await sfAPI.getUsageStats({
  startDate: '2025-01-01',
  endDate: '2025-01-31'
});

console.log(`Total Messages: ${stats.chat.messages}`);
console.log(`Total Cost: $${(stats.costs.total / 100).toFixed(2)}`);
console.log(`Active Users: ${stats.chat.uniqueUsers}`)

For detailed usage tracking documentation, see USAGE-TRACKING.md.

🔧 Development

Backend Structure

backend/src/
├── auth/              # API key authentication
├── materials/         # Content management
├── components/        # All component types (chat, flashcards, etc.)
├── embed/            # Embed token & routing
├── organizations/    # Publisher management  
├── usage/           # Usage tracking
└── common/          # Shared schemas & utilities

Adding New Features

1. Create a new module: nest g module feature-name
2. Add controller: nest g controller feature-name
3. Add service: nest g service feature-name
4. Update app.module.ts imports

Running Tests

cd backend
npm run test
npm run test:e2e

Authentication

This API supports two types of authentication:

1. API Key Authentication (Machine-to-Machine)

For server-to-server communication, use API keys in the x-api-key header:

curl -H "x-api-key: your-api-key" http://localhost:3000/api/components

2. JWT Token Authentication (Console/UI)

For interactive applications, use JWT tokens in the Authorization header:

1. Register a new user:

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "password123", "name": "John Doe"}'

2. Login to get a JWT token:

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "password123"}'

3. Use the JWT token for authenticated requests:

curl -H "Authorization: Bearer your-jwt-token" http://localhost:3000/auth/profile

Flexible Authentication

Most API endpoints accept both authentication methods. The system will try API key authentication first, and fall back to JWT token authentication if no API key is provided.

Test the authentication:

# Test with API key
curl -H "x-api-key: your-api-key" http://localhost:3000/auth/profile

# Test with JWT token  
curl -H "Authorization: Bearer your-jwt-token" http://localhost:3000/auth/profile