# Content Templates

**Version:** 0.1.0 _Auto-generated API documentation_

**Last Updated:** 2025-10-03

---

# API Reference

## API Types

### Interfaces

#### ContentTemplate

Content Templates Module Lecture and meditation templates with self-assessment
capabilities

```typescript
export type TemplateType = 'lecture' | 'meditation' | 'practice' | 'reflection';
export type DifficultyLevel =
  | 'beginner'
  | 'intermediate'
  | 'advanced'
  | 'expert';
export type ChecklistItemStatus =
  | 'pending'
  | 'in-progress'
  | 'completed'
  | 'skipped';
export type RatingScale = 1 | 2 | 3 | 4 | 5;

/**
 * Template metadata and structure
 */
export interface ContentTemplate {
  id: string;
  type: TemplateType;
  title: string;
  description: string;
  tradition?: string;
  difficulty: DifficultyLevel;
  duration: number; // in minutes
  tags: string[];
  sections: TemplateSection[];
  checklist?: ChecklistItem[];
  ratingCriteria?: RatingCriterion[];
  createdAt: Date;
  updatedAt: Date;
  version: string;
}
```

#### TemplateSection

Template section (introduction, main content, conclusion, etc.)

```typescript
export interface TemplateSection {
  id: string;
  title: string;
  content: string;
  type:
    | 'text'
    | 'audio_cue'
    | 'visual_cue'
    | 'instruction'
    | 'reflection_prompt';
  duration?: number; // section duration in seconds
  order: number;
  metadata?: Record<string, unknown>;
}
```

#### ChecklistItem

Self-assessment checklist item

```typescript
export interface ChecklistItem {
  id: string;
  text: string;
  category: string;
  order: number;
  required: boolean;
  status: ChecklistItemStatus;
  completedAt?: Date;
  notes?: string;
}
```

#### RatingCriterion

Self-rating criterion

```typescript
export interface RatingCriterion {
  id: string;
  dimension: string; // e.g., "focus", "relaxation", "understanding"
  question: string;
  scale: {
    min: RatingScale;
    max: RatingScale;
    labels: Record<RatingScale, string>;
  };
  order: number;
}
```

#### TemplateSession

User's session with a template

```typescript
export interface TemplateSession {
  id: string;
  templateId: string;
  userId: string;
  startedAt: Date;
  completedAt?: Date;
  checklistProgress: Map<string, ChecklistItemStatus>;
  ratings: Map<string, RatingScale>;
  notes: string;
  duration: number; // actual duration in minutes
}
```

#### CreateTemplateInput

Template creation/update input

```typescript
export interface CreateTemplateInput {
  type: TemplateType;
  title: string;
  description: string;
  tradition?: string;
  difficulty: DifficultyLevel;
  duration: number;
  tags: string[];
  sections: Omit<TemplateSection, 'id'>[];
  checklist?: Omit<ChecklistItem, 'id' | 'status' | 'completedAt'>[];
  ratingCriteria?: Omit<RatingCriterion, 'id'>[];
}
```

#### TemplateSearchOptions

Template search/filter options

```typescript
export interface TemplateSearchOptions {
  type?: TemplateType;
  tradition?: string;
  difficulty?: DifficultyLevel;
  minDuration?: number;
  maxDuration?: number;
  tags?: string[];
  limit?: number;
  offset?: number;
}
```

### Type Aliases

#### TemplateType

Content Templates Module Lecture and meditation templates with self-assessment
capabilities

```typescript
export type TemplateType = 'lecture' | 'meditation' | 'practice' | 'reflection';
```

#### DifficultyLevel

```typescript
export type DifficultyLevel =
  | 'beginner'
  | 'intermediate'
  | 'advanced'
  | 'expert';
```

#### ChecklistItemStatus

```typescript
export type ChecklistItemStatus =
  | 'pending'
  | 'in-progress'
  | 'completed'
  | 'skipped';
```

#### RatingScale

```typescript
export type RatingScale = 1 | 2 | 3 | 4 | 5;
```

### Classes

#### ContentTemplateRegistry

Content Templates Module Lecture and meditation templates with self-assessment
capabilities

```typescript
export type TemplateType = 'lecture' | 'meditation' | 'practice' | 'reflection';
export type DifficultyLevel = 'beginner' | 'intermediate' | 'advanced' | 'expert';
export type ChecklistItemStatus = 'pending' | 'in-progress' | 'completed' | 'skipped';
export type RatingScale = 1 | 2 | 3 | 4 | 5;

/**
 * Template metadata and structure
 */
export interface ContentTemplate {
  id: string;
  type: TemplateType;
  title: string;
  description: string;
  tradition?: string;
  difficulty: DifficultyLev...
```

# Endpoints

## Overview

The Content Templates API provides endpoints for creating, managing, and using
structured lecture and meditation templates with built-in self-assessment
capabilities.

## Base URL

```
http://localhost:3007/v1/ai
```

## Authentication

All endpoints require authentication via Bearer token in the Authorization
header.

## Endpoints

### Create Template

**POST** `/content-templates`

Creates a new content template.

**Request Body:**

```json
{
  "type": "lecture" | "meditation" | "practice" | "reflection",
  "title": "string",
  "description": "string",
  "tradition": "string (optional)",
  "difficulty": "beginner" | "intermediate" | "advanced" | "expert",
  "duration": number,
  "tags": ["string"],
  "sections": [{
    "title": "string",
    "content": "string",
    "type": "text" | "audio_cue" | "visual_cue" | "instruction" | "reflection_prompt",
    "duration": number (optional),
    "order": number
  }],
  "checklist": [{
    "text": "string",
    "category": "string",
    "order": number,
    "required": boolean
  }] (optional),
  "ratingCriteria": [{
    "dimension": "string",
    "question": "string",
    "scale": {
      "min": 1,
      "max": 5,
      "labels": {
        "1": "string",
        "2": "string",
        "3": "string",
        "4": "string",
        "5": "string"
      }
    },
    "order": number
  }] (optional)
}
```

**Response:** `201 Created`

```json
{
  "id": "tpl_xyz",
  "type": "lecture",
  "title": "Introduction to Mindfulness",
  "version": "1.0.0",
  "createdAt": "2025-10-03T00:00:00Z",
  ...
}
```

### List All Templates

**GET** `/content-templates`

Returns all available templates.

**Response:** `200 OK`

```json
{
  "templates": [...],
  "count": number
}
```

### Search Templates

**GET**
`/content-templates/search?type={type}&tradition={tradition}&difficulty={difficulty}&minDuration={min}&maxDuration={max}&tags={tag1,tag2}`

Search templates with filters.

**Query Parameters:**

- `type` (optional): Template type
- `tradition` (optional): Spiritual tradition
- `difficulty` (optional): Difficulty level
- `minDuration` (optional): Minimum duration in minutes
- `maxDuration` (optional): Maximum duration in minutes
- `tags` (optional): Comma-separated tags

**Response:** `200 OK`

```json
{
  "templates": [...],
  "count": number
}
```

### Get Template

**GET** `/content-templates/:id`

Retrieve a specific template by ID.

**Response:** `200 OK` or `404 Not Found`

### Update Template

**PUT** `/content-templates/:id`

Update an existing template. Increments version.

**Request Body:** Same as Create Template (partial updates supported)

**Response:** `200 OK` or `404 Not Found`

### Delete Template

**DELETE** `/content-templates/:id`

Delete a template.

**Response:** `204 No Content` or `404 Not Found`

### Start Session

**POST** `/content-templates/:id/sessions`

Start a practice session with a template.

**Request Body:**

```json
{
  "userId": "string"
}
```

**Response:** `201 Created`

```json
{
  "sessionId": "ses_xyz",
  "templateId": "tpl_abc",
  "userId": "user_123",
  "startedAt": "2025-10-03T00:00:00Z"
}
```

### Update Checklist Item

**PUT** `/sessions/:sessionId/checklist/:itemId`

Update a checklist item status during a session.

**Request Body:**

```json
{
  "status": "pending" | "in-progress" | "completed" | "skipped",
  "notes": "string (optional)"
}
```

**Response:** `200 OK`

### Add Rating

**POST** `/sessions/:sessionId/ratings`

Submit a self-rating for a session.

**Request Body:**

```json
{
  "criterionId": "string",
  "value": 1 | 2 | 3 | 4 | 5
}
```

**Response:** `200 OK`

### Complete Session

**POST** `/sessions/:sessionId/complete`

Mark a session as completed.

**Request Body:**

```json
{
  "notes": "string (optional)"
}
```

**Response:** `200 OK`

### Get User Sessions

**GET** `/users/:userId/sessions`

Retrieve session history for a user.

**Response:** `200 OK`

```json
{
  "sessions": [...],
  "count": number
}
```

## Data Models

### ContentTemplate

```typescript
{
  id: string;
  type: "lecture" | "meditation" | "practice" | "reflection";
  title: string;
  description: string;
  tradition?: string;
  difficulty: "beginner" | "intermediate" | "advanced" | "expert";
  duration: number; // in minutes
  tags: string[];
  sections: TemplateSection[];
  checklist?: ChecklistItem[];
  ratingCriteria?: RatingCriterion[];
  createdAt: Date;
  updatedAt: Date;
  version: string;
}
```

### TemplateSection

```typescript
{
  id: string;
  title: string;
  content: string;
  type: "text" | "audio_cue" | "visual_cue" | "instruction" | "reflection_prompt";
  duration?: number; // in seconds
  order: number;
  metadata?: Record<string, unknown>;
}
```

### ChecklistItem

```typescript
{
  id: string;
  text: string;
  category: string;
  order: number;
  required: boolean;
  status: "pending" | "in-progress" | "completed" | "skipped";
  completedAt?: Date;
  notes?: string;
}
```

### RatingCriterion

```typescript
{
  id: string;
  dimension: string;
  question: string;
  scale: {
    min: 1 | 2 | 3 | 4 | 5;
    max: 1 | 2 | 3 | 4 | 5;
    labels: Record<1 | 2 | 3 | 4 | 5, string>;
  }
  order: number;
}
```

### TemplateSession

```typescript
{
  id: string;
  templateId: string;
  userId: string;
  startedAt: Date;
  completedAt?: Date;
  checklistProgress: Map<string, ChecklistItemStatus>;
  ratings: Map<string, RatingScale>;
  notes: string;
  duration: number; // actual duration in minutes
}
```

## Error Responses

All endpoints return standard error responses:

**400 Bad Request**

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Template title cannot be empty"
  }
}
```

**404 Not Found**

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Template 'tpl_xyz' not found"
  }
}
```

**500 Internal Server Error**

```json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}
```

## Examples

### Create a Meditation Template

```bash
curl -X POST http://localhost:3007/v1/ai/content-templates \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "meditation",
    "title": "Mindful Breathing Practice",
    "description": "A guided breathing meditation for beginners",
    "tradition": "Buddhist",
    "difficulty": "beginner",
    "duration": 10,
    "tags": ["breathing", "mindfulness", "beginner"],
    "sections": [
      {
        "title": "Introduction",
        "content": "Find a comfortable seated position...",
        "type": "instruction",
        "order": 1
      },
      {
        "title": "Main Practice",
        "content": "Focus on your natural breath...",
        "type": "audio_cue",
        "duration": 480,
        "order": 2
      },
      {
        "title": "Closing",
        "content": "Slowly return your awareness...",
        "type": "instruction",
        "order": 3
      }
    ],
    "checklist": [
      {
        "text": "Did you maintain focus on your breath?",
        "category": "practice",
        "order": 1,
        "required": false
      },
      {
        "text": "Did you notice when your mind wandered?",
        "category": "awareness",
        "order": 2,
        "required": false
      }
    ],
    "ratingCriteria": [
      {
        "dimension": "relaxation",
        "question": "How relaxed did you feel during the practice?",
        "scale": {
          "min": 1,
          "max": 5,
          "labels": {
            "1": "Very tense",
            "2": "Somewhat tense",
            "3": "Neutral",
            "4": "Somewhat relaxed",
            "5": "Very relaxed"
          }
        },
        "order": 1
      }
    ]
  }'
```

### Search for Beginner Meditations

```bash
curl -X GET "http://localhost:3007/v1/ai/content-templates/search?type=meditation&difficulty=beginner" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Start a Practice Session

```bash
curl -X POST http://localhost:3007/v1/ai/content-templates/tpl_xyz/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123"
  }'
```

## Test Coverage

The Content Templates feature has comprehensive test coverage:

- **Unit Tests**: 41 tests (100% code coverage)
- **Integration Tests**: 20 tests (all HTTP endpoints)
- **Total**: 61 tests passing

## Implementation

- **Language**: TypeScript with strict type safety
- **File**: `apps/lilith/svc-ai/src/content-templates.ts`
- **Lines of Code**: 356
- **Dependencies**: None (in-memory storage)

## Limitations

- Templates are stored in-memory (not persisted to database)
- No pagination on list endpoints
- Session data is not persisted
- No real-time synchronization across instances

## Future Enhancements

- Database persistence (PostgreSQL)
- Pagination and cursor-based navigation
- Real-time session updates via WebSocket
- Template versioning and rollback
- Template sharing and publishing
- Community ratings and reviews

# Implementation Status

## Implementation Status

**Current Status:** **14/15 Criteria Met (93% Complete)** ✅

**Completion:** 14/15 criteria met (93%)
