Add example handler implementations for app-todo and app-crm actions

Provides actual function bodies for previously dangling target string
references: completeTask, startTask, cloneTask, massCompleteTasks,
deleteCompletedTasks, exportTasksToCSV (todo); convertLead, addToCampaign,
cloneRecord, massUpdateStage, escalateCase, closeCase, markAsPrimaryContact,
exportToCSV (crm).

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

examples/app-crm/src/actions/handlers/case.handlers.ts

@@ -0,0 +1,46 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Case Action Handlers
+ *
+ * Handler implementations for actions defined in case.actions.ts.
+ *
+ * @example Registration:
+ * ```ts
+ * engine.registerAction('case', 'escalateCase', escalateCase);
+ * engine.registerAction('case', 'closeCase', closeCase);
+ * ```
+ */
+
+interface ActionContext {
+  record: Record<string, unknown>;
+  user: { id: string; name: string };
+  engine: {
+    update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
+  };
+  params?: Record<string, unknown>;
+}
+
+/** Escalate a case to the escalation team */
+export async function escalateCase(ctx: ActionContext): Promise<void> {
+  const { record, engine, user, params } = ctx;
+  await engine.update('case', record._id as string, {
+    is_escalated: true,
+    escalation_reason: params?.reason as string,
+    escalated_by: user.id,
+    escalated_at: new Date().toISOString(),
+    priority: 'urgent',
+  });
+}
+
+/** Close a case with a resolution */
+export async function closeCase(ctx: ActionContext): Promise<void> {
+  const { record, engine, user, params } = ctx;
+  await engine.update('case', record._id as string, {
+    is_closed: true,
+    resolution: params?.resolution as string,
+    closed_by: user.id,
+    closed_at: new Date().toISOString(),
+    status: 'closed',
+  });
+}

examples/app-crm/src/actions/handlers/contact.handlers.ts

@@ -0,0 +1,37 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Contact Action Handlers
+ *
+ * Handler implementations for actions defined in contact.actions.ts.
+ *
+ * @example Registration:
+ * ```ts
+ * engine.registerAction('contact', 'markAsPrimaryContact', markAsPrimaryContact);
+ * ```
+ */
+
+interface ActionContext {
+  record: Record<string, unknown>;
+  user: { id: string; name: string };
+  engine: {
+    update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
+    find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+  };
+  params?: Record<string, unknown>;
+}
+
+/** Mark a contact as the primary contact for its account */
+export async function markAsPrimaryContact(ctx: ActionContext): Promise<void> {
+  const { record, engine } = ctx;
+  const accountId = record.account_id as string;
+
+  // Clear existing primary contacts on the same account
+  const siblings = await engine.find('contact', { account_id: accountId, is_primary: true });
+  for (const sibling of siblings) {
+    await engine.update('contact', sibling._id as string, { is_primary: false });
+  }
+
+  // Set current contact as primary
+  await engine.update('contact', record._id as string, { is_primary: true });
+}

examples/app-crm/src/actions/handlers/global.handlers.ts

@@ -0,0 +1,34 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Global Action Handlers
+ *
+ * Handler implementations for cross-domain actions defined in global.actions.ts.
+ *
+ * @example Registration:
+ * ```ts
+ * engine.registerAction('*', 'exportToCSV', exportToCSV);
+ * ```
+ */
+
+interface ActionContext {
+  record: Record<string, unknown>;
+  user: { id: string; name: string };
+  engine: {
+    find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+  };
+  params?: Record<string, unknown>;
+}
+
+/** Export records of a given object to CSV format */
+export async function exportToCSV(ctx: ActionContext): Promise<string> {
+  const { params, engine } = ctx;
+  const objectName = (params?.objectName ?? 'account') as string;
+  const records = await engine.find(objectName, {});
+  if (records.length === 0) return '';
+
+  const keys = Object.keys(records[0]);
+  const header = keys.join(',');
+  const rows = records.map((r) => keys.map((k) => r[k] ?? '').join(','));
+  return [header, ...rows].join('\n');
+}

examples/app-crm/src/actions/handlers/index.ts

@@ -0,0 +1,12 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Action Handler Implementations Barrel
+ *
+ * Re-exports all handler functions for registration via engine.registerAction().
+ */
+export { convertLead, addToCampaign } from './lead.handlers';
+export { cloneRecord, massUpdateStage } from './opportunity.handlers';
+export { escalateCase, closeCase } from './case.handlers';
+export { markAsPrimaryContact } from './contact.handlers';
+export { exportToCSV } from './global.handlers';

examples/app-crm/src/actions/handlers/lead.handlers.ts

@@ -0,0 +1,87 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Lead Action Handlers
+ *
+ * Handler implementations for lead-domain actions defined in lead.actions.ts.
+ * The `ConvertLeadAction` (type: flow) is handled by the flow engine;
+ * `CreateCampaignAction` (type: modal) is handled by the UI modal system.
+ *
+ * This file provides the server-side logic backing these actions.
+ *
+ * @example Registration:
+ * ```ts
+ * engine.registerAction('lead', 'convertLead', convertLead);
+ * ```
+ */
+
+interface ActionContext {
+  record: Record<string, unknown>;
+  user: { id: string; name: string };
+  engine: {
+    update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
+    insert(object: string, data: Record<string, unknown>): Promise<{ _id: string }>;
+    find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+  };
+  params?: Record<string, unknown>;
+}
+
+/** Convert a qualified lead into Account, Contact, and Opportunity records */
+export async function convertLead(ctx: ActionContext): Promise<{
+  accountId: string;
+  contactId: string;
+  opportunityId: string;
+}> {
+  const { record, engine, user } = ctx;
+
+  const account = await engine.insert('account', {
+    name: record.company as string,
+    website: record.website,
+    industry: record.industry,
+    created_by: user.id,
+  });
+
+  const contact = await engine.insert('contact', {
+    first_name: record.first_name,
+    last_name: record.last_name,
+    email: record.email,
+    phone: record.phone,
+    account_id: account._id,
+  });
+
+  const opportunity = await engine.insert('opportunity', {
+    name: `${record.company} - New Opportunity`,
+    account_id: account._id,
+    contact_id: contact._id,
+    stage: 'prospecting',
+    amount: record.estimated_value ?? 0,
+  });
+
+  await engine.update('lead', record._id as string, {
+    is_converted: true,
+    status: 'converted',
+    converted_account_id: account._id,
+    converted_contact_id: contact._id,
+    converted_opportunity_id: opportunity._id,
+  });
+
+  return {
+    accountId: account._id,
+    contactId: contact._id,
+    opportunityId: opportunity._id,
+  };
+}
+
+/** Add selected leads to a campaign */
+export async function addToCampaign(ctx: ActionContext): Promise<void> {
+  const { params, engine } = ctx;
+  const campaignId = params?.campaign as string;
+  const leadIds = (params?.selectedIds ?? []) as string[];
+  for (const leadId of leadIds) {
+    await engine.insert('campaign_member', {
+      campaign_id: campaignId,
+      lead_id: leadId,
+      status: 'sent',
+    });
+  }
+}

examples/app-crm/src/actions/handlers/opportunity.handlers.ts

@@ -0,0 +1,44 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Opportunity Action Handlers
+ *
+ * Handler implementations for actions defined in opportunity.actions.ts.
+ *
+ * @example Registration:
+ * ```ts
+ * engine.registerAction('opportunity', 'cloneRecord', cloneRecord);
+ * ```
+ */
+
+interface ActionContext {
+  record: Record<string, unknown>;
+  user: { id: string; name: string };
+  engine: {
+    update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
+    insert(object: string, data: Record<string, unknown>): Promise<{ _id: string }>;
+    find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+  };
+  params?: Record<string, unknown>;
+}
+
+/** Clone an opportunity record */
+export async function cloneRecord(ctx: ActionContext): Promise<{ _id: string }> {
+  const { record, engine } = ctx;
+  const { _id, created_at, updated_at, ...fields } = record as Record<string, unknown>;
+  return engine.insert('opportunity', {
+    ...fields,
+    name: `Copy of ${fields.name ?? 'Untitled'}`,
+    stage: 'prospecting',
+  });
+}
+
+/** Mass update opportunity stage for selected records */
+export async function massUpdateStage(ctx: ActionContext): Promise<void> {
+  const { params, engine } = ctx;
+  const newStage = params?.stage as string;
+  const ids = (params?.selectedIds ?? []) as string[];
+  for (const id of ids) {
+    await engine.update('opportunity', id, { stage: newStage });
+  }
+}

examples/app-todo/src/actions/task.handlers.ts

@@ -0,0 +1,97 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Task Action Handlers
+ *
+ * Example handler implementations for actions defined in task.actions.ts.
+ * Each handler is registered via `engine.registerAction()` and referenced
+ * by name through the action's `target` field.
+ *
+ * @example Registration (in a plugin or config bootstrap):
+ * ```ts
+ * engine.registerAction('task', 'completeTask', completeTask);
+ * engine.registerAction('task', 'startTask', startTask);
+ * ```
+ */
+
+// ─── Handler Context (simplified for example purposes) ──────────────
+interface ActionContext {
+  /** The record being acted upon */
+  record: Record<string, unknown>;
+  /** Current authenticated user */
+  user: { id: string; name: string };
+  /** Data engine for CRUD operations */
+  engine: {
+    update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
+    insert(object: string, data: Record<string, unknown>): Promise<{ _id: string }>;
+    find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+    delete(object: string, ids: string[]): Promise<void>;
+  };
+  /** Action parameters (from user input / params) */
+  params?: Record<string, unknown>;
+}
+
+/** Mark a single task as complete */
+export async function completeTask(ctx: ActionContext): Promise<void> {
+  const { record, engine, user } = ctx;
+  await engine.update('task', record._id as string, {
+    status: 'completed',
+    completed_at: new Date().toISOString(),
+    completed_by: user.id,
+  });
+}
+
+/** Mark a task as in-progress */
+export async function startTask(ctx: ActionContext): Promise<void> {
+  const { record, engine } = ctx;
+  await engine.update('task', record._id as string, {
+    status: 'in_progress',
+    started_at: new Date().toISOString(),
+  });
+}
+
+/** Clone a task (duplicate with reset status) */
+export async function cloneTask(ctx: ActionContext): Promise<{ _id: string }> {
+  const { record, engine } = ctx;
+  const { _id, created_at, updated_at, completed_at, completed_by, ...fields } = record as Record<string, unknown>;
+  return engine.insert('task', {
+    ...fields,
+    status: 'not_started',
+    subject: `Copy of ${fields.subject ?? 'Untitled'}`,
+  });
+}
+
+/** Mark all selected tasks as complete (bulk) */
+export async function massCompleteTasks(ctx: ActionContext): Promise<void> {
+  const { params, engine, user } = ctx;
+  const ids = (params?.selectedIds ?? []) as string[];
+  const now = new Date().toISOString();
+  for (const id of ids) {
+    await engine.update('task', id, {
+      status: 'completed',
+      completed_at: now,
+      completed_by: user.id,
+    });
+  }
+}
+
+/** Delete all completed tasks */
+export async function deleteCompletedTasks(ctx: ActionContext): Promise<void> {
+  const { engine } = ctx;
+  const completed = await engine.find('task', { status: 'completed' });
+  const ids = completed.map((r) => r._id as string);
+  if (ids.length > 0) {
+    await engine.delete('task', ids);
+  }
+}
+
+/** Export tasks to CSV format */
+export async function exportTasksToCSV(ctx: ActionContext): Promise<string> {
+  const { engine } = ctx;
+  const tasks = await engine.find('task', {});
+  const header = 'subject,status,priority,category,due_date';
+  const rows = tasks.map((t) =>
+    [t.subject, t.status, t.priority, t.category, t.due_date ?? ''].join(','),
+  );
+  return [header, ...rows].join('\n');
+}