npm package: @santillana-ai/create-tutor-app
Description: Create a new Santillana AI Tutor application
Author: Santillana AI Team
Latest version: 5.9.0

# @santillana-ai/create-tutor-app

Create a new Santillana AI Tutor application with one command.

## Quick Start

```bash
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

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

### With API key (non-interactive)

```bash
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`:

```env
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:

```bash
npm run dev
```

Open [http://localhost:3000](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](https://your-dashboard-url).

## 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)

```typescript
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: "user@example.com" })
```

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

## Learn More

- [Santillana AI Tutor SDK Documentation](https://docs.santillana-ai.com)
- [Next.js Documentation](https://nextjs.org/docs)
- [API Reference](https://api-docs.santillana-ai.com)

## Support

For issues and questions:
- [GitHub Issues](https://github.com/santillana-ai/tutor-sdk/issues)
- [Documentation](https://docs.santillana-ai.com)
- [Community Forum](https://community.santillana-ai.com)