Data Management API Reference¶

// List entities with filters
const users = await pt.list({
    entityNames: ['user', 'product'],
    filters: {
        status: 'active',
        age: { $gte: 18 }
    },
    limit: 10,
    offset: 0
});

// List multiple entity types
const entities = await pt.list({
    entityNames: ['task', 'event', 'user'],
    filters: { status: 'active' }
});

// Process results
const tasks = entities.filter(e => e.entity_name === 'task');
const events = entities.filter(e => e.entity_name === 'event');
const users = entities.filter(e => e.entity_name === 'user');

// Without metadata (default)
[
    {
        id: 123,
        entity_name: 'task',
        data: { text: 'Buy groceries', completed: false },
        creator_user_id: 456,
        created_at: '2024-03-15T10:30:00+00:00',
        updated_at: '2024-03-15T10:35:00+00:00'
    },
    // ... more entities
]

// With metadata (returnMetadata: true)
{
    entities: [...],    // Array of entity objects
    count: 20,          // Number of items in this response
    pagination: {
        limit: 20,      // Items requested
        offset: 40,     // Starting position
        has_more: true, // true if full page returned (more likely exists)
        page: 3,        // Current page (if page-based)
        page_size: 20   // Items per page (if page-based)
    }
}

// Get entity by ID
const task = await pt.get(123);
console.log(task.data.text);
console.log(task.created_at);

// Get and edit pattern (using merge mode)
const task = await pt.get(123);
await pt.edit(123, {
    completed: !task.data.completed
}, true);

try {
    const task = await pt.get(123);
    console.log('Found:', task.data);
} catch (error) {
    console.error('Entity not found or unauthorized:', error);
}

// Add a task
const result = await pt.add('task', {
    text: 'Buy groceries',
    completed: false
});

// Add an event
const event = await pt.add('event', {
    title: 'Team Meeting',
    date: '2024-03-20',
    time: '14:00',
    description: 'Weekly sync'
});

// The creator_user_id is automatically set to the current user
console.log(result.creator_user_id); // Automatically populated

[
    {
        success: true,
        entity: {
            id: 1,
            entity_name: 'task',
            creator_user_id: 42,
            data: { title: 'Task 1' },
            created_at: '2025-01-20T10:00:00Z',
            updated_at: '2025-01-20T10:00:00Z'
        },
        error: null,
        index: 0
    },
    {
        success: false,
        entity: null,
        error: {
            message: 'Validation failed',
            type: 'ValidationError'
        },
        index: 1
    }
]

// Create multiple tasks at once
const results = await pt.batchAdd('task', [
    { text: 'Buy groceries', completed: false },
    { text: 'Call dentist', completed: false },
    { text: 'Review PR', completed: false }
]);

// Check results
const successful = results.filter(r => r.success);
const failed = results.filter(r => !r.success);

console.log(`Created ${successful.length} tasks`);
if (failed.length > 0) {
    console.log(`Failed to create ${failed.length} tasks`);
    failed.forEach(f => console.error(`Item ${f.index}: ${f.error.message}`));
}

// Import data from CSV or API
async function importUsers(userData) {
    const results = await pt.batchAdd('user', userData);

    return {
        imported: results.filter(r => r.success).length,
        failed: results.filter(r => !r.success).length,
        errors: results.filter(r => !r.success).map(r => ({
            index: r.index,
            error: r.error.message
        }))
    };
}

// Bulk data entry
async function bulkAddProducts(products) {
    try {
        const results = await pt.batchAdd('product', products);

        // Get IDs of successfully created products
        const createdIds = results
            .filter(r => r.success)
            .map(r => r.entity.id);

        return createdIds;
    } catch (error) {
        console.error('Batch add failed:', error);
        return [];
    }
}

// Get current data first to preserve fields
const task = await pt.get(taskId);

// Update with merged data manually
const updated = await pt.edit(taskId, {
    ...task.data,
    completed: true
});

// Only update specific fields - other fields are preserved automatically
const updated = await pt.edit(taskId, {
    completed: true
}, true);

// Update multiple fields without fetching first
await pt.edit(taskId, {
    status: 'in_progress',
    priority: 'high'
}, true);

// Toggle a field using merge mode
async function toggleTaskCompletion(taskId) {
    const task = await pt.get(taskId);
    await pt.edit(taskId, {
        completed: !task.data.completed
    }, true);
}

// Fetch entity with its timestamp
const task = await pt.get(taskId);

// User edits the task...
// Meanwhile, another user might also be editing it

// Try to save with optimistic locking
const result = await pt.edit(
    taskId,
    {
        ...task.data,
        status: 'completed'
    },
    false,  // merge mode
    task.updated_at  // Only update if not modified since this timestamp
);

// Handle conflicts
if (result.conflict) {
    // Another user modified this task
    console.log('Conflict detected!');
    console.log('Your version:', task.data);
    console.log('Current version:', result.currentEntity.data);

    // Show conflict resolution UI to user
    showConflictDialog(task.data, result.currentEntity.data);
} else {
    // Update successful
    console.log('Task updated successfully');
}

// Real-world conflict handling example
async function safeEdit(taskId, updates) {
    const task = await pt.get(taskId);

    try {
        const result = await pt.edit(
            taskId,
            { ...task.data, ...updates },
            false,
            task.updated_at
        );

        if (result.conflict) {
            // Let user decide how to resolve
            const userChoice = await askUser(
                'This task was modified by someone else. What would you like to do?',
                ['Use my changes', 'Use their changes', 'Merge manually']
            );

            if (userChoice === 'Use my changes') {
                // Force update without timestamp check
                return await pt.edit(taskId, { ...task.data, ...updates });
            } else if (userChoice === 'Merge manually') {
                // Show merge interface
                return await showMergeInterface(task.data, result.currentEntity.data, updates);
            } else {
                // Keep their changes
                return result.currentEntity;
            }
        }

        return result;
    } catch (error) {
        console.error('Edit failed:', error);
        throw error;
    }
}

// ❌ BAD: This removes all other fields (replace mode)
await pt.edit(123, { completed: true });

// ✅ GOOD: Use merge mode for partial updates
await pt.edit(123, { completed: true }, true);

// ✅ ALSO GOOD: Manually merge with existing data
const task = await pt.get(123);
await pt.edit(123, {
    ...task.data,
    completed: true
});

{
    id: number,                    // Entity ID (required)
    data: object,                  // New data (required)
    merge: boolean,                // Merge mode (optional, default: false)
    if_unchanged_since: string     // ISO timestamp for optimistic locking (optional)
}

[
    {
        success: true,
        entity: {
            id: 1,
            entity_name: 'task',
            data: { title: 'Updated Task', completed: true },
            created_at: '2025-01-20T10:00:00Z',
            updated_at: '2025-01-20T11:00:00Z'
        },
        conflict: false
    },
    {
        success: false,
        conflict: true,
        currentEntity: {
            id: 2,
            entity_name: 'task',
            data: { title: 'Already modified by someone else' },
            created_at: '2025-01-20T10:00:00Z',
            updated_at: '2025-01-20T10:45:00Z'  // Changed since our if_unchanged_since
        }
    }
]

// Bulk status update
const taskIds = [1, 2, 3, 4, 5];
const results = await pt.batchEdit(
    taskIds.map(id => ({
        id: id,
        data: { completed: true },
        merge: true  // Preserve other fields
    }))
);

console.log(`Updated ${results.filter(r => r.success).length} tasks`);

// Update multiple items with different values
const updates = [
    { id: 1, data: { status: 'completed', priority: 'low' }, merge: true },
    { id: 2, data: { status: 'in_progress', priority: 'high' }, merge: true },
    { id: 3, data: { status: 'pending', priority: 'medium' }, merge: true }
];

const results = await pt.batchEdit(updates);

// Handle conflicts
results.forEach((result, index) => {
    if (result.conflict) {
        console.warn(`Item ${index} has conflict:`, result.currentEntity);
        // Show conflict resolution UI to user
    } else if (!result.success) {
        console.error(`Item ${index} failed to update`);
    }
});

// Optimistic locking for batch updates
async function safeBatchUpdate(entities) {
    const items = entities.map(entity => ({
        id: entity.id,
        data: { status: 'archived' },
        merge: true,
        if_unchanged_since: entity.updated_at
    }));

    const results = await pt.batchEdit(items);

    // Separate successful updates and conflicts
    const successful = results.filter(r => r.success && !r.conflict);
    const conflicts = results.filter(r => r.conflict);

    return { successful, conflicts };
}

// Bulk field update with validation
async function bulkUpdatePriority(taskIds, newPriority) {
    // Fetch all tasks first to preserve other fields
    const tasks = await Promise.all(
        taskIds.map(id => pt.get(id))
    );

    // Prepare updates
    const items = tasks.map(task => ({
        id: task.id,
        data: {
            ...task.data,
            priority: newPriority,
            last_modified_by: 'admin'
        }
    }));

    const results = await pt.batchEdit(items);

    return {
        updated: results.filter(r => r.success).length,
        failed: results.filter(r => !r.success).length
    };
}

// Simple delete
async function deleteTask(taskId) {
    try {
        await pt.delete(taskId);
        console.log('Task deleted successfully');
    } catch (error) {
        console.error('Error deleting task:', error);
    }
}

// Delete with confirmation
async function deleteTaskSafely(taskId) {
    try {
        const task = await pt.get(taskId);

        if (confirm(`Delete task: "${task.data.text}"?`)) {
            await pt.delete(taskId);
            console.log('Task deleted successfully');
        }
    } catch (error) {
        alert('Task not found or already deleted');
    }
}

// Bulk delete
async function bulkDeleteTasks(taskIds) {
    const results = [];

    for (const id of taskIds) {
        try {
            await pt.delete(id);
            results.push({ id, success: true });
        } catch (error) {
            results.push({ id, success: false, error: error.message });
        }
    }

    return results;
}

[
    {
        id: 1,
        success: true,
        error: null
    },
    {
        id: 2,
        success: false,
        error: "Entity not found"
    }
]

// Delete multiple tasks
const taskIds = [1, 2, 3, 4, 5];
const results = await pt.batchDelete(taskIds);

// Check results
const deleted = results.filter(r => r.success);
const failed = results.filter(r => !r.success);

console.log(`Deleted ${deleted.length} tasks`);
if (failed.length > 0) {
    console.warn(`Failed to delete ${failed.length} tasks`);
    failed.forEach(f => console.error(`ID ${f.id}: ${f.error}`));
}

// Clean up old completed tasks
async function archiveCompletedTasks() {
    // Get completed tasks older than 30 days
    const oldTasks = await pt.list({
        entityNames: ['task'],
        filters: {
            completed: "true",
            completed_date: { $lt: '2024-12-20' }
        }
    });

    if (oldTasks.length === 0) {
        return { deleted: 0 };
    }

    const ids = oldTasks.map(t => t.id);
    const results = await pt.batchDelete(ids);

    return {
        deleted: results.filter(r => r.success).length,
        failed: results.filter(r => !r.success).length
    };
}

// Delete with user confirmation
async function deleteSelectedItems(selectedIds) {
    if (selectedIds.length === 0) {
        alert('No items selected');
        return;
    }

    if (!confirm(`Delete ${selectedIds.length} items? This cannot be undone.`)) {
        return;
    }

    const results = await pt.batchDelete(selectedIds);

    const successCount = results.filter(r => r.success).length;
    alert(`Deleted ${successCount} of ${selectedIds.length} items`);

    await loadData(); // Refresh the list
}

// Bulk cleanup with error handling
async function bulkDelete(entityName, filters) {
    try {
        // Get entities to delete
        const entities = await pt.list({
            entityNames: [entityName],
            filters: filters
        });

        if (entities.length === 0) {
            return { message: 'No entities found matching criteria' };
        }

        // Delete them
        const ids = entities.map(e => e.id);
        const results = await pt.batchDelete(ids);

        const successful = results.filter(r => r.success);
        const failed = results.filter(r => !r.success);

        return {
            total: entities.length,
            deleted: successful.length,
            failed: failed.length,
            errors: failed.map(f => ({ id: f.id, error: f.error }))
        };
    } catch (error) {
        console.error('Bulk delete failed:', error);
        return { error: error.message };
    }
}

// Usage example
const result = await bulkDelete('task', {
    status: 'archived',
    archived_date: { $lt: '2024-01-01' }
});

console.log(result);
// { total: 150, deleted: 148, failed: 2, errors: [...] }

[
  {
    "id": 123,              // Member ID (either user_id or agent_id)
    "type": "user",         // "user" or "agent"
    "name": "John Doe",     // Display name (full name for users, agent name for agents)

    // User-only fields (null for agents):
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",

    "is_chat_owner": true,  // Created the chat
    "is_logged_user": true  // This is the current user making the request
  },
  {
    "id": 456,
    "type": "agent",
    "name": "AI Assistant",

    // User fields are null for agents
    "first_name": null,
    "last_name": null,
    "email": null,

    "is_chat_owner": false,
    "is_logged_user": false  // Always false for agents
  }
]

// Get and display all members
const members = await pt.getChatMembers();
members.forEach(member => {
    const icon = member.type === 'user' ? '👤' : '🤖';
    console.log(`${icon} ${member.name}`);
});

// Filter by type
const users = members.filter(m => m.type === 'user');
const agents = members.filter(m => m.type === 'agent');
console.log(`Users: ${users.length}, Agents: ${agents.length}`);

// Create task assignment dropdown (users only)
async function createAssigneeDropdown() {
    const members = await pt.getChatMembers();
    const users = members.filter(m => m.type === 'user');

    const options = users
        .map(m => `<option value="${m.id}">${m.name}</option>`)
        .join('');

    return `
        <select id="assignee">
            <option value="">Unassigned</option>
            ${options}
        </select>
    `;
}

// Get current user
const members = await pt.getChatMembers();
const currentUser = members.find(m => m.is_logged_user);

{
  "chat_id": 42,
  "name": "Project Planning",
  "created_at": "2025-01-15T10:30:00Z"
}

// Get current chat details
const chatInfo = await pt.getChatInfo();
console.log(`Chat: ${chatInfo.name}`);
console.log(`ID: ${chatInfo.chat_id}`);
console.log(`Created: ${chatInfo.created_at}`);

// Display chat header
const info = await pt.getChatInfo();
document.getElementById('chatName').textContent = info.name;
document.getElementById('chatId').textContent = `ID: ${info.chat_id}`;

// Show chat age
const info = await pt.getChatInfo();
const created = new Date(info.created_at);
const age = Math.floor((Date.now() - created) / (1000 * 60 * 60 * 24));
console.log(`Chat is ${age} days old`);

// Build page title with chat name
async function initializePage() {
    const chatInfo = await pt.getChatInfo();
    document.title = `${chatInfo.name} - Dashboard`;

    const header = document.getElementById('pageHeader');
    header.innerHTML = `
        <h1>${chatInfo.name}</h1>
        <p class="text-gray-600">Chat ID: ${chatInfo.chat_id}</p>
    `;
}

// Use chat ID in API calls
const chatInfo = await pt.getChatInfo();
const apiUrl = `/api/v1/chats/${chatInfo.chat_id}/custom-endpoint`;

{
    "success": true,
    "chat_id": 42,
    "name": "New Chat Name"
}

// Simple rename
await pt.renameChat('New Chat Name');

// With user input
const newName = prompt('Enter new chat name:');
if (newName) {
    await pt.renameChat(newName);
}

// Rename with confirmation and error handling
async function renameChatWithConfirmation() {
    const chatInfo = await pt.getChatInfo();
    const newName = prompt(`Rename "${chatInfo.name}" to:`, chatInfo.name);

    if (newName && newName !== chatInfo.name) {
        try {
            const result = await pt.renameChat(newName);
            if (result.success) {
                console.log(`Chat renamed to: ${result.name}`);
            }
        } catch (error) {
            console.error('Failed to rename chat:', error);
        }
    }
}

{
    users_mentions: [
        {
            id: 1,
            mention_name: "@john",
            display_name: "John Doe",
            // ... additional user fields
        }
    ],
    virtual_assistants_mentions: [
        {
            id: 5,
            mention_name: "@assistant",
            name: "My Assistant",
            // ... additional assistant fields
        }
    ],
    chats_mentions: [
        {
            id: 10,
            mention_name: "#project-chat",
            chat_name: "Project Chat",
            // ... additional chat fields
        }
    ],
    tasks_mentions: [
        {
            id: 20,
            mention_name: "@task:generate-report",
            // ... additional task fields
        }
    ]
}

// Get all available mentions
const mentions = await pt.getAvailableMentions();

// Build a mention picker UI
async function createMentionPicker() {
    const mentions = await pt.getAvailableMentions();

    const html = `
        <div class="mention-picker">
            ${mentions.users_mentions.length > 0 ? `
                <h3>Users</h3>
                ${mentions.users_mentions.map(user => `
                    <div class="mention-item" data-mention="${user.mention_name}">
                        👤 ${user.display_name} (${user.mention_name})
                    </div>
                `).join('')}
            ` : ''}

            ${mentions.virtual_assistants_mentions.length > 0 ? `
                <h3>Virtual Assistants</h3>
                ${mentions.virtual_assistants_mentions.map(va => `
                    <div class="mention-item" data-mention="${va.mention_name}">
                        🤖 ${va.name} (${va.mention_name})
                    </div>
                `).join('')}
            ` : ''}

            ${mentions.chats_mentions.length > 0 ? `
                <h3>Other Chats</h3>
                ${mentions.chats_mentions.map(chat => `
                    <div class="mention-item" data-mention="${chat.mention_name}">
                        💬 ${chat.chat_name} (${chat.mention_name})
                    </div>
                `).join('')}
            ` : ''}

            ${mentions.tasks_mentions.length > 0 ? `
                <h3>Tasks</h3>
                ${mentions.tasks_mentions.map(task => `
                    <div class="mention-item" data-mention="${task.mention_name}">
                        ⚡ ${task.mention_name}
                    </div>
                `).join('')}
            ` : ''}
        </div>
    `;

    return html;
}

// Auto-complete mentions in textarea
async function setupMentionAutocomplete(textareaId) {
    const mentions = await pt.getAvailableMentions();
    const textarea = document.getElementById(textareaId);

    // Flatten all mentions
    const allMentions = [
        ...mentions.users_mentions.map(m => ({...m, type: 'user'})),
        ...mentions.virtual_assistants_mentions.map(m => ({...m, type: 'assistant'})),
        ...mentions.chats_mentions.map(m => ({...m, type: 'chat'})),
        ...mentions.tasks_mentions.map(m => ({...m, type: 'task'}))
    ];

    textarea.addEventListener('input', (e) => {
        const value = e.target.value;
        const atIndex = value.lastIndexOf('@');
        const hashIndex = value.lastIndexOf('#');
        const mentionStart = Math.max(atIndex, hashIndex);

        if (mentionStart >= 0) {
            const searchText = value.substring(mentionStart).toLowerCase();
            const matches = allMentions.filter(m =>
                m.mention_name.toLowerCase().includes(searchText)
            );

            if (matches.length > 0) {
                showMentionSuggestions(matches, mentionStart);
            }
        }
    });
}

// Send message with mentions
async function sendMessageWithMention(userId) {
    const mentions = await pt.getAvailableMentions();
    const user = mentions.users_mentions.find(u => u.id === userId);

    if (user) {
        await pt.addMessage(`Hey ${user.mention_name}, can you review this?`);
    }
}

// Check what entities user can mention
async function checkMentionPermissions() {
    const mentions = await pt.getAvailableMentions();

    return {
        canMentionUsers: mentions.users_mentions.length > 0,
        canMentionAssistants: mentions.virtual_assistants_mentions.length > 0,
        canMentionChats: mentions.chats_mentions.length > 0,
        canMentionTasks: mentions.tasks_mentions.length > 0
    };
}

await pt.initDb();

// Reload the page
pt.reload();

// Example: Reload after a major update
async function refreshApplication() {
    await pt.initDb();
    pt.reload();
}

// Navigate to another Live Page
pt.navigate(456);

// Example: Navigation menu
function createNavigation(livePages) {
    return livePages.map(page => `
        <button onclick="pt.navigate(${page.id})">
            ${page.title}
        </button>
    `).join('');
}

pt.addMessage(message, options?)

pt.addMessage(formOrFormData, message, options?)

// Simple text message
async function sendNotification() {
    try {
        const response = await pt.addMessage('Task completed successfully!');
        console.log('Message sent with ID:', response.result.user_message.id);
        console.log('Task ID for tracking:', response.result.task_id);

        // Check if AI responded
        if (response.result.ai_responses && response.result.ai_responses.length > 0) {
            console.log('AI replied:', response.result.ai_responses[0].message);
        }
    } catch (error) {
        console.error('Error sending message:', error);
    }
}

// With options
await pt.addMessage('Processing...', {
    hidden: true,
    awaitResponse: false
});

// Wait for AI response
const result = await pt.addMessage('What is 2+2?', {
    awaitResponse: true
});
console.log('AI says:', result.ai_responses[0].message);

// Send notification after an action
async function completeTask(taskId) {
    const task = await pt.get(taskId);
    await pt.edit(taskId, { completed: true }, true);  // merge mode

    // Notify the chat
    await pt.addMessage(`Task "${task.data.text}" has been completed!`);
}

// From HTML form
const form = document.getElementById('uploadForm');
await pt.addMessage(form, 'Check out these files!');

// From FormData
const formData = new FormData();
formData.append('files', file1);
formData.append('files', file2);
await pt.addMessage(formData, 'Here are the documents');

// Files only, no message text
await pt.addMessage(form, '');

// Files with options
const result = await pt.addMessage(formData, 'Analyze these files', {
    awaitResponse: true,
    hidden: false
});
console.log(`Uploaded ${result.result.files_count} files`);

// Access attachment information
if (result.result.attachments) {
    result.result.attachments.forEach(attachment => {
        console.log('File:', attachment.name);
        console.log('Status:', attachment.document.status);
        console.log('Download URL:', attachment.document.download_url);
        console.log('Preview:', attachment.document.short_description);
    });
}

// Access AI responses
if (result.result.ai_responses) {
    result.result.ai_responses.forEach(response => {
        console.log('AI:', response.message);
    });
}

// Hidden message with files
await pt.addMessage(form, 'Internal processing...', {
    hidden: true
});

// Upload files to a specific folder
const form = document.getElementById('uploadForm');
await pt.addMessage(form, 'Monthly report', { folder: 'reports/january' });

// Combine folder with other options
await pt.addMessage(formData, 'Analyze these invoices', {
    folder: 'invoices/2024',
    awaitResponse: true
});