@santillana-ai/create-tutor-app

Create a new Santillana AI Tutor application with one command.

Quick Start

npx @santillana-ai/create-tutor-app my-tutor-app

This will:

• Create a new Next.js project with the Santillana AI Tutor SDK pre-configured
• Ask for your API key interactively
• Install all dependencies
• Optionally start the development server

Features

The generated app includes:

• ✅ Next.js 15 with TypeScript
• ✅ Santillana AI Tutor SDK (@santillana-ai/typescript-tutor-sdk) pre-configured
• ✅ Complete UI examples for activities and sessions
• ✅ API routes with proper error handling using the latest SDK methods
• ✅ Tailwind CSS for styling
• ✅ ESLint configuration
• ✅ Type-safe API calls with full TypeScript support

Usage

Basic usage

npx @santillana-ai/create-tutor-app my-app
cd my-app
npm run dev

With API key (non-interactive)

npx @santillana-ai/create-tutor-app my-app
# Follow the prompts to enter your API key

Manual API key setup

If you skip the API key during creation, edit .env.local:

NEXT_PUBLIC_API_KEY=your_api_key_here
NEXT_PUBLIC_API_URL=https://8hk4zapik5.execute-api.us-east-1.amazonaws.com/prod/api/v1

Project Structure

my-tutor-app/
├── app/
│   ├── api/                           # Next.js API routes
│   │   ├── activities/                # Activity management endpoints
│   │   │   ├── route.ts               # List and create activities
│   │   │   └── [activityId]/          # Get, update, delete specific activity
│   │   ├── sessions/                  # Session management endpoints
│   │   │   ├── route.ts               # List and create sessions
│   │   │   └── [sessionId]/           # Session-specific operations
│   │   │       ├── messages/          # Send and retrieve messages
│   │   │       ├── progress/          # Get session progress
│   │   │       └── reset/             # Reset session state
│   │   └── users/                     # User management endpoints
│   ├── globals.css                    # Global styles
│   ├── layout.tsx                     # App layout
│   └── page.tsx                       # Main page with full example
├── lib/
│   ├── sdk-client-server.ts          # Server-side SDK instance
│   ├── types.ts                       # TypeScript type definitions
│   └── error-handler.ts               # Error handling utilities
├── components/                         # React components
├── hooks/                             # Custom React hooks
├── .env.local                         # Environment variables
└── package.json

Development

Start the development server:

npm run dev

Open http://localhost:3000 in your browser.

API Key

You need a Santillana AI Tutor API key to use this template. Get yours from the Santillana AI Tutor Dashboard.

Examples Included

The generated app includes working examples of:

• Activity browsing - List and view available learning activities using activities.listActivities()
• Session management - Create, resume, and manage learning sessions with sessions.createSession()
• Interactive chat - Send messages and receive AI responses using sessions.sendMessage()
• User management - Create and authenticate users with users.createUser() and users.findUserByEmail()
• Free sessions - Start sessions without specific activities using custom session configurations
• Error handling - Proper error states and user feedback with type-safe error responses

SDK Usage Examples

Server-side (API Routes)

import { activitiesSDK, sessionsSDK, usersSDK } from "@/lib/sdk-client-server"

// List activities
const activities = await activitiesSDK.listActivities({ limit: 10 })

// Create a session
const session = await sessionsSDK.createSession({
  userId: "user-id",
  activityId: "activity-id", // Optional
  sessionConfig: { /* config */ } // Optional, for free sessions
})

// Send a message
const response = await sessionsSDK.sendMessage({
  sessionId: "session-id",
  sendMessageRequestDto: {
    message: "Hello!",
    userId: "user-id"
  }
})

// Find user by email
const user = await usersSDK.findUserByEmail({ email: "[email protected]" })

All SDK methods are fully typed and return typed responses for excellent IDE support.

Learn More

• Santillana AI Tutor SDK Documentation
• Next.js Documentation
• API Reference

Support

For issues and questions:

• GitHub Issues
• Documentation
• Community Forum