Teams App Developer

interface WorkflowDefinition {
  id: string;                          // Unique workflow identifier
  name: string;                        // Display name
  description: string;                 // Used in command suggestions and AI descriptions
  commandPrefix: string;               // e.g., "/pto", "/book", "/standup"

  // Schema
  columns: ColumnDefinition[];         // Maps to SharePoint List columns
  statusField: string;                 // Which column tracks lifecycle state
  statusValues: {
    active: string[];                  // e.g., ["Pending", "InProgress"]
    completed: string[];               // e.g., ["Approved", "Rejected", "Done"]
  };

  // Triggers
  triggers: TriggerConfig[];

  // Routing
  routing?: {
    type: "none" | "single" | "sequential" | "parallel-any" | "parallel-all";
    approverSource: "fixed" | "manager" | "field";  // Where to find the approver
    approverField?: string;            // Column name if approverSource is "field"
    escalationTimeoutMs?: number;
  };

  // Cards
  cards: {
    active: (record: any) => object;
    completed: (record: any) => object;
    list: (records: any[]) => object;
    form?: () => object;               // For message extension action trigger
  };

  // AI
  queryDescription: string;            // Describes when AI should call the query function
  filterableColumns: string[];         // Columns exposed as AI function parameters
}

interface ColumnDefinition {
  name: string;
  type: "text" | "number" | "dateTime" | "choice" | "personOrGroup" | "boolean";
  choices?: string[];                  // For choice columns
  required?: boolean;
}

interface TriggerConfig {
  type: "command" | "messageExtension" | "scheduled" | "stateChange";
  config: Record<string, any>;         // Trigger-specific configuration
}

function registerWorkflow(app: any, engine: WorkflowEngine, definition: WorkflowDefinition) {
  // Command trigger
  const commandTrigger = definition.triggers.find((t) => t.type === "command");
  if (commandTrigger) {
    const regex = new RegExp(`^\\${definition.commandPrefix}\\s*(.*)$`, "i");
    app.message(regex, async (ctx: any) => {
      await engine.handleCommand(ctx, definition);
    });
  }

  // Scheduled trigger
  const scheduledTrigger = definition.triggers.find((t) => t.type === "scheduled");
  if (scheduledTrigger) {
    cron.schedule(scheduledTrigger.config.cron, async () => {
      await engine.handleScheduled(definition);
    });
  }

  // Register AI query function
  engine.registerQueryFunction(definition);
}

class WorkflowEngine {
  private definitions = new Map<string, WorkflowDefinition>();
  private graphClient: Client;
  private siteId: string;
  private lists = new Map<string, string>(); // workflowId -> listId

  async handleCommand(ctx: any, def: WorkflowDefinition) {
    const params = parseCommandParams(ctx.activity.text!, def);
    const record = await this.createRecord(def, {
      ...params,
      requesterId: ctx.activity.from?.aadObjectId,
      requesterName: ctx.activity.from?.name,
      conversationId: ctx.activity.conversation?.id,
      serviceUrl: ctx.activity.serviceUrl,
    });

    const card = def.cards.active(record);
    const response = await ctx.send({
      attachments: [{
        contentType: "application/vnd.microsoft.card.adaptive",
        content: card,
      }],
    });

    // Store activity ID for future updates
    await this.updateRecordField(def, record.id, "CardActivityId", response.id);

    // Start escalation timer if routing is configured
    if (def.routing?.escalationTimeoutMs) {
      this.startEscalation(def, record);
    }
  }

  async handleAction(ctx: any, verb: string, data: any) {
    const def = this.definitions.get(data.workflowId);
    if (!def) return;

    const record = await this.getRecord(def, data.recordId);

    if (verb === "approve" || verb === "reject") {
      return this.processApproval(ctx, def, record, verb, data.comment);
    }

    if (verb.startsWith("refresh")) {
      const card = record.status === "completed"
        ? def.cards.completed(record)
        : def.cards.active(record);
      return {
        status: 200,
        body: {
          statusCode: 200,
          type: "application/vnd.microsoft.card.adaptive",
          value: card,
        },
      };
    }
  }

  registerQueryFunction(def: WorkflowDefinition) {
    // Auto-generate AI function schema from definition
    const parameters: Record<string, any> = {};
    for (const col of def.filterableColumns) {
      const colDef = def.columns.find((c) => c.name === col);
      if (!colDef) continue;

      switch (colDef.type) {
        case "choice":
          parameters[col] = { type: "string", enum: colDef.choices };
          break;
        case "dateTime":
          parameters[col] = { type: "string", description: `Filter by ${col} (ISO date)` };
          break;
        case "personOrGroup":
          parameters[col] = { type: "string", description: `Filter by ${col} name` };
          break;
        default:
          parameters[col] = { type: "string" };
      }
    }

    return {
      name: `query_${def.id}`,
      description: def.queryDescription,
      parameters: { type: "object", properties: parameters },
    };
  }

  private async createRecord(def: WorkflowDefinition, fields: Record<string, any>) {
    const listId = await this.ensureList(def);
    const item = await this.graphClient
      .api(`/sites/${this.siteId}/lists/${listId}/items`)
      .post({ fields });
    return { id: item.id, ...item.fields };
  }

  private async ensureList(def: WorkflowDefinition): Promise<string> {
    if (this.lists.has(def.id)) return this.lists.get(def.id)!;

    // Check if list exists, create if not
    try {
      const existing = await this.graphClient
        .api(`/sites/${this.siteId}/lists`)
        .filter(`displayName eq '${def.name}'`)
        .get();

      if (existing.value.length > 0) {
        this.lists.set(def.id, existing.value[0].id);
        return existing.value[0].id;
      }
    } catch { /* List doesn't exist */ }

    const list = await this.graphClient
      .api(`/sites/${this.siteId}/lists`)
      .post({
        displayName: def.name,
        list: { template: "genericList" },
        columns: def.columns.map(colDefToGraphColumn),
      });

    this.lists.set(def.id, list.id);
    return list.id;
  }
}

const ptoWorkflow: WorkflowDefinition = {
  id: "pto",
  name: "PTO Requests",
  description: "Time-off and vacation request workflow",
  commandPrefix: "/pto",
  columns: [
    { name: "Requester", type: "personOrGroup", required: true },
    { name: "StartDate", type: "dateTime", required: true },
    { name: "EndDate", type: "dateTime", required: true },
    { name: "HoursRequested", type: "number" },
    { name: "Status", type: "choice", choices: ["Pending", "Approved", "Rejected"] },
    { name: "ApprovedBy", type: "personOrGroup" },
    { name: "Reason", type: "text" },
  ],
  statusField: "Status",
  statusValues: {
    active: ["Pending"],
    completed: ["Approved", "Rejected"],
  },
  triggers: [
    { type: "command", config: { pattern: "/pto START to END" } },
    { type: "messageExtension", config: { commandId: "createPto" } },
  ],
  routing: {
    type: "single",
    approverSource: "manager",
    escalationTimeoutMs: 48 * 60 * 60 * 1000, // 48 hours
  },
  cards: {
    active: buildPtoActiveCard,
    completed: buildPtoCompletedCard,
    list: buildPtoListCard,
  },
  queryDescription: "Query PTO/time-off requests. Use when user asks about PTO, vacation, leave, days off.",
  filterableColumns: ["Status", "Requester", "StartDate"],
};

// Register
registerWorkflow(app, engine, ptoWorkflow);