@okrlinkhub/agent-factory 3.0.0 → 3.0.1

package/src/component/lib.test.ts

@@ -201,6 +201,131 @@ describe("component lib", () => {
     expect(claim?.payload.messageText).toBe("hello");
   });
 
+  test("message templates should normalize tags and auto-generate key", async () => {
+    const t = initConvexTest();
+
+    const templateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "  Status Update ",
+      text: "  Share your latest progress. ",
+      tags: [" Urgent ", "follow-up", "urgent", " Team "],
+      actorUserId: "user-admin-1",
+    });
+
+    expect(templateId).toBeDefined();
+
+    const templates = await t.query(api.lib.listMessageTemplatesByCompany, {
+      includeDisabled: true,
+    });
+
+    expect(templates).toHaveLength(1);
+    expect(templates[0]).toMatchObject({
+      templateKey: "status-update",
+      title: "Status Update",
+      text: "Share your latest progress.",
+      tags: ["follow-up", "team", "urgent"],
+      usageCount: 0,
+      enabled: true,
+    });
+  });
+
+  test("message templates should generate a unique key globally", async () => {
+    const t = initConvexTest();
+
+    const firstTemplateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "Daily check-in",
+      text: "Share your update.",
+      tags: [],
+      actorUserId: "user-admin-1",
+    });
+
+    const secondTemplateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "Daily check-in",
+      text: "Duplicate title",
+      tags: [],
+      actorUserId: "user-admin-2",
+    });
+
+    const templates = await t.query(api.lib.listMessageTemplatesByCompany, {
+      includeDisabled: true,
+    });
+
+    expect(firstTemplateId).toBeDefined();
+    expect(secondTemplateId).toBeDefined();
+    expect(templates.map((template) => template.templateKey).sort()).toEqual([
+      "daily-check-in",
+      "daily-check-in-2",
+    ]);
+  });
+
+  test("message templates should track usage and surface most used templates first", async () => {
+    const t = initConvexTest();
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "template-agent",
+      version: "1.0.0",
+      secretsRef: [],
+      enabled: true,
+    });
+    await t.mutation(api.lib.bindUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      source: "manual",
+      metadata: { companyId: "co-templates" },
+    });
+
+    const firstTemplateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "Weekly recap",
+      text: "Condividi il recap della settimana.",
+      tags: ["weekly", "recap"],
+      actorUserId: "user-admin-1",
+    });
+    const secondTemplateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "Quick nudge",
+      text: "Mandami un aggiornamento rapido.",
+      tags: ["follow-up"],
+      actorUserId: "user-admin-1",
+    });
+
+    await t.mutation((api.lib as any).sendMessageTemplateToUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      templateId: firstTemplateId,
+    });
+    await t.mutation((api.lib as any).sendMessageTemplateToUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      templateId: firstTemplateId,
+    });
+    await t.mutation((api.lib as any).sendMessageTemplateToUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      templateId: secondTemplateId,
+    });
+
+    const templates = await t.query(api.lib.listMessageTemplatesByCompany, {
+      includeDisabled: true,
+    });
+
+    expect(templates.map((template) => ({
+      title: template.title,
+      usageCount: template.usageCount,
+    }))).toEqual([
+      { title: "Weekly recap", usageCount: 2 },
+      { title: "Quick nudge", usageCount: 1 },
+    ]);
+
+    const queuedItems = await t.query(api.lib.listQueueItemsForUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      limit: 10,
+    });
+    expect(queuedItems).toHaveLength(3);
+    expect(queuedItems.map((item) => item.payload.messageText).sort()).toEqual([
+      "Condividi il recap della settimana.",
+      "Condividi il recap della settimana.",
+      "Mandami un aggiornamento rapido.",
+    ].sort());
+  });
+
   test("message runtime config should store telegram attachment retention", async () => {
     const t = initConvexTest();
     await t.mutation(api.lib.setMessageRuntimeConfig, {

package/src/component/lib.ts

@@ -23,6 +23,7 @@ export {
   listQueueItemsForUserAgent,
   getConversationViewForUserAgent,
   sendMessageToUserAgent,
+  sendMessageTemplateToUserAgent,
   listSnapshotsForConversation,
   listSnapshotsForUserAgent,
   getLatestSnapshotForUserAgent,
@@ -59,6 +60,13 @@ export {
   getWebhookReadiness,
 } from "./identity.js";
 
+export {
+  createMessageTemplate,
+  updateMessageTemplate,
+  deleteMessageTemplate,
+  listMessageTemplatesByCompany,
+} from "./messageTemplates.js";
+
 export {
   createPushTemplate,
   updatePushTemplate,

package/src/component/messageTemplates.ts

@@ -0,0 +1,205 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+import type { MutationCtx } from "./_generated/server.js";
+
+const messageTemplateViewValidator = v.object({
+  _id: v.id("messageTemplates"),
+  templateKey: v.string(),
+  title: v.string(),
+  text: v.string(),
+  tags: v.array(v.string()),
+  usageCount: v.number(),
+  enabled: v.boolean(),
+  createdBy: v.string(),
+  updatedBy: v.string(),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+function normalizeTemplateKey(value: string) {
+  return value.trim().toLowerCase();
+}
+
+function buildTemplateKeyBase(title: string) {
+  const normalized = title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "message-template";
+}
+
+function normalizeTitle(value: string) {
+  return value.trim();
+}
+
+function normalizeText(value: string) {
+  return value.trim();
+}
+
+function normalizeTags(tags: Array<string>) {
+  return Array.from(
+    new Set(
+      tags
+        .map((tag) => tag.trim().toLowerCase())
+        .filter((tag) => tag.length > 0),
+    ),
+  ).sort((left, right) => left.localeCompare(right));
+}
+
+function validateMessageTemplateFields(input: {
+  title?: string;
+  text?: string;
+}) {
+  if (input.title !== undefined && input.title.length === 0) {
+    throw new Error("Template title is required");
+  }
+  if (input.text !== undefined && input.text.length === 0) {
+    throw new Error("Template text is required");
+  }
+}
+
+async function resolveUniqueTemplateKey(
+  ctx: MutationCtx,
+  title: string,
+  currentTemplateId?: string,
+) {
+  const baseKey = buildTemplateKeyBase(title);
+  let candidate = baseKey;
+  let suffix = 2;
+
+  while (true) {
+    const existing = await ctx.db
+      .query("messageTemplates")
+      .withIndex("by_templateKey", (q) => q.eq("templateKey", candidate))
+      .unique();
+    if (!existing || String(existing._id) === currentTemplateId) {
+      return candidate;
+    }
+    candidate = `${baseKey}-${suffix}`;
+    suffix += 1;
+  }
+}
+
+export const createMessageTemplate = mutation({
+  args: {
+    title: v.string(),
+    text: v.string(),
+    tags: v.array(v.string()),
+    enabled: v.optional(v.boolean()),
+    actorUserId: v.string(),
+    nowMs: v.optional(v.number()),
+  },
+  returns: v.id("messageTemplates"),
+  handler: async (ctx, args) => {
+    const title = normalizeTitle(args.title);
+    const text = normalizeText(args.text);
+    const tags = normalizeTags(args.tags);
+    validateMessageTemplateFields({ title, text });
+    const templateKey = normalizeTemplateKey(await resolveUniqueTemplateKey(ctx, title));
+
+    const nowMs = args.nowMs ?? Date.now();
+    return await ctx.db.insert("messageTemplates", {
+      templateKey,
+      title,
+      text,
+      tags,
+      usageCount: 0,
+      enabled: args.enabled ?? true,
+      createdBy: args.actorUserId,
+      updatedBy: args.actorUserId,
+      createdAt: nowMs,
+      updatedAt: nowMs,
+    });
+  },
+});
+
+export const updateMessageTemplate = mutation({
+  args: {
+    templateId: v.id("messageTemplates"),
+    title: v.optional(v.string()),
+    text: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    enabled: v.optional(v.boolean()),
+    actorUserId: v.string(),
+    nowMs: v.optional(v.number()),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const template = await ctx.db.get(args.templateId);
+    if (!template) return false;
+
+    const title = args.title !== undefined ? normalizeTitle(args.title) : template.title;
+    const text = args.text !== undefined ? normalizeText(args.text) : template.text;
+    const tags = args.tags !== undefined ? normalizeTags(args.tags) : template.tags;
+    validateMessageTemplateFields({ title, text });
+    const templateKey =
+      title !== template.title
+        ? normalizeTemplateKey(await resolveUniqueTemplateKey(ctx, title, String(template._id)))
+        : template.templateKey;
+
+    const nowMs = args.nowMs ?? Date.now();
+    await ctx.db.patch(template._id, {
+      templateKey,
+      title,
+      text,
+      tags,
+      enabled: args.enabled ?? template.enabled,
+      updatedBy: args.actorUserId,
+      updatedAt: nowMs,
+    });
+    return true;
+  },
+});
+
+export const deleteMessageTemplate = mutation({
+  args: {
+    templateId: v.id("messageTemplates"),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const template = await ctx.db.get(args.templateId);
+    if (!template) return false;
+    await ctx.db.delete(template._id);
+    return true;
+  },
+});
+
+export const listMessageTemplatesByCompany = query({
+  args: {
+    includeDisabled: v.optional(v.boolean()),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(messageTemplateViewValidator),
+  handler: async (ctx, args) => {
+    const includeDisabled = args.includeDisabled ?? false;
+    const limit = Math.max(1, Math.min(args.limit ?? 100, 200));
+
+    const rows = includeDisabled
+      ? await ctx.db.query("messageTemplates").take(limit)
+      : await ctx.db
+          .query("messageTemplates")
+          .withIndex("by_enabled", (q) => q.eq("enabled", true))
+          .take(limit);
+
+    rows.sort((left, right) => {
+      if (right.usageCount !== left.usageCount) {
+        return right.usageCount - left.usageCount;
+      }
+      return right.updatedAt - left.updatedAt;
+    });
+    return rows.map((row) => ({
+      _id: row._id,
+      templateKey: row.templateKey,
+      title: row.title,
+      text: row.text,
+      tags: row.tags,
+      usageCount: row.usageCount,
+      enabled: row.enabled,
+      createdBy: row.createdBy,
+      updatedBy: row.updatedBy,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    }));
+  },
+});

package/src/component/queue.ts

@@ -2013,6 +2013,67 @@ export const sendMessageToUserAgent = mutation({
   },
 });
 
+export const sendMessageTemplateToUserAgent = mutation({
+  args: {
+    consumerUserId: v.string(),
+    agentKey: v.string(),
+    templateId: v.id("messageTemplates"),
+    metadata: v.optional(v.record(v.string(), v.string())),
+    nowMs: v.optional(v.number()),
+    providerConfig: v.optional(providerConfigValidator),
+  },
+  returns: v.object({
+    messageId: v.id("messageQueue"),
+    usageCount: v.number(),
+  }),
+  handler: async (ctx, args) => {
+    const template = await ctx.db.get(args.templateId);
+    if (!template || !template.enabled) {
+      throw new Error("Message template not found");
+    }
+
+    const nowMs = args.nowMs ?? Date.now();
+    const target = await resolveConversationTargetForUserAgent(
+      ctx,
+      args.consumerUserId,
+      args.agentKey,
+      true,
+    );
+    const providerUserId =
+      target.telegramUserId ?? target.telegramChatId ?? args.consumerUserId;
+    const usageCount = template.usageCount + 1;
+    const messageId = await enqueueMessageRecord(ctx, {
+      conversationId: target.conversationId,
+      agentKey: args.agentKey,
+      payload: {
+        provider: target.provider,
+        providerUserId,
+        messageText: template.text,
+        metadata: {
+          ...(args.metadata ?? {}),
+          consumerUserId: args.consumerUserId,
+          source: "message_template",
+          templateId: String(template._id),
+          templateKey: template.templateKey,
+          ...(target.telegramChatId ? { telegramChatId: target.telegramChatId } : {}),
+          ...(target.telegramUserId ? { telegramUserId: target.telegramUserId } : {}),
+        },
+      },
+      scheduledFor: nowMs,
+      providerConfig: args.providerConfig,
+    });
+
+    await ctx.db.patch(template._id, {
+      usageCount,
+    });
+
+    return {
+      messageId,
+      usageCount,
+    };
+  },
+});
+
 export const listSnapshotsForConversation = query({
   args: {
     conversationId: v.string(),

package/src/component/schema.ts

@@ -410,6 +410,21 @@ export default defineSchema({
     .index("by_companyId_and_templateKey", ["companyId", "templateKey"])
     .index("by_companyId_and_enabled", ["companyId", "enabled"]),
 
+  messageTemplates: defineTable({
+    templateKey: v.string(),
+    title: v.string(),
+    text: v.string(),
+    tags: v.array(v.string()),
+    usageCount: v.number(),
+    enabled: v.boolean(),
+    createdBy: v.string(),
+    updatedBy: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_templateKey", ["templateKey"])
+    .index("by_enabled", ["enabled"]),
+
   messagePushJobs: defineTable({
     companyId: v.string(),
     consumerUserId: v.string(),