Kaimeleon Temporal SDK

A type-safe SDK for interacting with Kaimeleon's Temporal workflows. This SDK provides comprehensive DTOs (Data Transfer Objects) and ORM interfaces for managing various domain entities.

Overview

The SDK is organized into two main directories:

• src/models/ - Contains all DTOs for data transfer and API communication
• src/orm/ - Contains repository interfaces and implementations for database operations

Common DTOs

Pagination & Search

Located in src/models/common/common.dto.ts

• PaginationDto: Basic pagination parameters (page, limit)
• SearchPaginationDto: Extended pagination with search and sorting capabilities
• PaginatedResponseDto: Standardized paginated response format
• SortDirection: Enum for ASC/DESC sorting

Domain-Specific DTOs

Todos Module

Located in src/models/todo/

Core DTOs:

• TodoDto: Main todo entity with properties like title, description, status, priority, dueDate, tags
• TodoTableRow: Database representation of a todo
• TodoStatus: Enum (TODO, IN_PROGRESS, DONE, ARCHIVED)
• TodoPriority: Enum (LOW, MEDIUM, HIGH, URGENT)

Request/Response DTOs:

• PostTodoRequestDto: Create todo request
• PutTodoRequestDto: Update todo request
• GetTodosQuery: Query parameters for listing todos with filtering
• GetTodosResponseDto: Paginated todo list response

Meetings Module

Located in src/models/meeting/

Core DTOs:

• MeetingDto: Meeting entity with title, date, duration, summary, keyPoints, actionItems, decisionsMade
• MeetingTableRow: Database representation
• MeetingAgendaRefDto: Reference to associated agenda
• MeetingTranscriptionDto: Associated transcription data

Request/Response DTOs:

• PostMeetingRequestDto: Create meeting request
• PutMeetingRequestDto: Update meeting request
• GetMeetingsQuery: Query parameters with date filtering
• UpdateMeetingAgendaItemsDto: Update agenda items discussed status

Meeting Agendas Module

Located in src/models/meeting-agenda/

Core DTOs:

• MeetingAgendaDto: Agenda with categories and items
• MeetingAgendaCategoryDto: Category with ordered items
• MeetingAgendaItemDto: Individual agenda item with optional duration and order fields

Request/Response DTOs:

• PostMeetingAgendaRequestDto: Create agenda request
• PutMeetingAgendaRequestDto: Update agenda request
• GetMeetingAgendasQuery: Query parameters for listing

Conversations Module

Located in src/models/conversations/

Core DTOs:

• ConversationDto: Conversation with messages array
• ConversationMessageDto: Individual message with role (user/assistant/system)
• ConversationSummaryDto: Lightweight conversation summary

Request/Response DTOs:

• PostConversationRequestDto: Create/append to conversation
• GetConversationsQuery: Query with channel filtering
• GetConversationByIdResponseDto: Full conversation with messages

Email Processing Module

Located in src/models/mail/

Core DTOs:

• EmailProcessingResultDto: Email analysis results with classification, priority, sentiment
• EmailActionDto: Automated actions (archive, delete, label, forward, reply)
• EmailExtractedTaskDto: Tasks extracted from emails
• EmailResponseDraftDto: Generated email response drafts

Enums:

• EmailClassification: IMPORTANT, PERSONAL, WORK, NEWSLETTER, SPAM, OTHER
• EmailPriority: HIGH, MEDIUM, LOW
• EmailSentiment: POSITIVE, NEUTRAL, NEGATIVE
• EmailActionType: ARCHIVE, DELETE, LABEL, FORWARD, REPLY, SNOOZE

Transcriptions Module

Located in src/models/transcriptions/

Core DTOs:

• TranscriptionDto: Full transcription with paragraphs
• TranscriptionParagraph: Speaker-separated paragraph with sentences
• TranscriptionSentence: Individual sentence with timestamps

User Preferences Module

Located in src/models/user-preferences/

Core DTOs:

• UserAccountDto: User account with credits, subscription, preferences
• UserPreferencesDto: User settings (personality, theme, language)
• AuthProvidersDto: Connected auth providers (Gmail, Telegram)

Integration Modules

Telegram (src/models/telegram/):

• TelegramConnectionDto: Connection status and details

Deepgram (src/models/deepgram/):

• DeepgramKeyDto: API key management
• DeepgramTranscriptionRequestDto: Transcription requests

Gmail Auth (src/models/gmail-auth/):

• GmailAuthUrlResponseDto: OAuth URL generation
• GmailAuthTokenResponseDto: Token exchange

ORM Repository Interfaces

Base Repository

Located in src/orm/base/

• IBaseRepository<TDto, TTableRow>: Base interface for DTO/TableRow conversion

Domain Repositories

Todo Repository (src/orm/todos/):

• createForUser(): Create todo for user
• list(): List todos with pagination and filtering
• findByUserIdAndId(): Get specific todo
• updateForUser(): Update todo
• updateStatus(): Update todo status with automatic completedAt handling
• deleteForUser(): Delete todo (returns {deleted: boolean, rowCount: number})
• processQueryParams(): Process and validate query parameters

Meeting Repository (src/orm/meetings/):

• Standard CRUD operations
• findByTranscriptionId(): Find meeting by transcription
• listWithTranscriptions(): List meetings with their transcriptions included
• findByUserIdAndIdWithTranscription(): Get meeting with full transcription
• validateDateRange(): Validate date range parameters
• deleteForUser(): Delete meeting (returns {deleted: boolean, rowCount: number})

Meeting Agenda Repository (src/orm/meeting-agendas/):

• Standard CRUD operations for agendas

Conversation Repository (src/orm/conversations/):

• createOrUpdate(): Upsert conversation with 5 parameters (userId, contextId, channel, title, message)
• getMessages(): Get conversation messages
• findByUserIdAndId(): Get conversation by ID
• findByUserIdAndIdWithMessages(): Get conversation with all messages
• findByContextId(): Find conversation by context ID
• updateTitle(): Update conversation title
• deleteForUser(): Delete conversation (returns {deleted: boolean, rowCount: number})
• deleteByContextId(): Delete by context ID (returns {deleted: boolean, rowCount: number})

Email Repositories (src/orm/emails/):

• EmailProcessingResultRepository: Store email analysis
• EmailActionRepository: Manage email actions
• EmailExtractedTaskRepository: Handle extracted tasks
• EmailResponseDraftRepository: Manage draft responses

Transcription Repository (src/orm/transcriptions/):

• createForUser(): Create transcription
• findByContextId(): Find by context ID
• findByUserIdAndId(): Get specific transcription
• updateForUser(): Update transcription
• deleteForUser(): Delete transcription (returns {deleted: boolean, rowCount: number})

User Account Repositories (src/orm/user-accounts/):

• UserAccountRepository: Manage user accounts
• UserPreferencesRepository: Handle user preferences

Usage

import { TodoDto, ITodoRepository } from '@kaimeleon/temporal-sdk';

// DTOs are used for API communication
const newTodo: TodoDto = {
  id: '123',
  userId: 'user-456',
  title: 'Complete SDK documentation',
  status: TodoStatus.TODO,
  priority: TodoPriority.HIGH,
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
};

// Repository interfaces define database operations
const repository: ITodoRepository = getTodoRepository();
const createdTodo = await repository.createForUser('user-456', newTodo);

Architecture Notes

• DTOs use camelCase for property names
• TableRows use snake_case matching database columns
• All timestamps are ISO 8601 strings
• Repositories handle user-scoped operations for security
• Pagination is standardized across all list operations
• All delete operations return {deleted: boolean, rowCount: number} for consistency
• Repository methods handle completedAt timestamps automatically for status changes
• Transcriptions are fetched by context_id (not foreign key) for flexibility

Version History

v1.4.1

• Added enhanced ORM methods for better service layer abstraction:
  • listWithTranscriptions() and findByUserIdAndIdWithTranscription() for Meeting repository
  • updateStatus() with automatic completedAt handling for Todo repository
  • findByContextId() and deleteByContextId() for Conversation repository
  • validateDateRange() for Meeting repository
  • processQueryParams() for Todo repository
• Standardized all delete operations to return {deleted: boolean, rowCount: number}
• Updated MeetingAgendaItemDto to remove discussed field and add optional duration
• Added updateForUser() method to Transcription repository
• Fixed transcription fetching to use context_id instead of foreign key references