Eve library

Content Templates

Guide

Revision 1

On this page

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#

text
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%)