@okrlinkhub/okrhub 0.1.0

package/src/component/entities/initiatives.ts

@@ -0,0 +1,342 @@
+/**
+ * Initiatives Entity for OKRHub Component
+ *
+ * CRUD operations and queries for Initiatives.
+ */
+
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server.js";
+import type { Id } from "../_generated/dataModel.js";
+import { generateExternalId } from "../externalId.js";
+import { assertValidExternalId, generateSlug } from "../lib/validation.js";
+import {
+  initiativePayloadValidator,
+  PrioritySchema,
+  InitiativeStatusSchema,
+  SyncStatusSchema,
+} from "../schema.js";
+
+// ============================================================================
+// LOCAL CRUD MUTATIONS
+// ============================================================================
+
+/**
+ * Creates an initiative locally and queues for sync
+ * Note: relativeImpact/overallImpact/isNew are set by linkhub based on priority
+ */
+export const createInitiative = mutation({
+  args: {
+    sourceApp: v.string(),
+    sourceUrl: v.optional(v.string()),
+    description: v.string(),
+    teamExternalId: v.string(),
+    riskExternalId: v.string(), // Required: Reference to risk
+    assigneeExternalId: v.string(),
+    createdByExternalId: v.string(),
+    status: v.optional(InitiativeStatusSchema), // Optional in input, default ON_TIME
+    priority: PrioritySchema,
+    finishedAt: v.optional(v.number()),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    externalId: v.string(),
+    localId: v.id("initiatives"),
+    queueId: v.optional(v.id("syncQueue")),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const {
+      sourceApp,
+      sourceUrl,
+      description,
+      teamExternalId,
+      riskExternalId,
+      assigneeExternalId,
+      createdByExternalId,
+      status,
+      priority,
+      finishedAt,
+    } = args;
+
+    try {
+      assertValidExternalId(teamExternalId, "teamExternalId");
+      assertValidExternalId(assigneeExternalId, "assigneeExternalId");
+      assertValidExternalId(createdByExternalId, "createdByExternalId");
+      assertValidExternalId(riskExternalId, "riskExternalId");
+
+      const externalId = generateExternalId(sourceApp, "initiative");
+      const slug = generateSlug(sourceApp, description.substring(0, 30));
+      const now = Date.now();
+
+      const localId = await ctx.db.insert("initiatives", {
+        externalId,
+        description,
+        teamExternalId,
+        riskExternalId,
+        assigneeExternalId,
+        createdByExternalId,
+        status: status ?? "ON_TIME", // Default to ON_TIME
+        priority,
+        finishedAt,
+        slug,
+        syncStatus: "pending",
+        createdAt: now,
+      });
+
+      const payload = JSON.stringify({
+        externalId,
+        description,
+        teamExternalId,
+        riskExternalId,
+        assigneeExternalId,
+        createdByExternalId,
+        status: status ?? "ON_TIME", // Default to ON_TIME
+        priority,
+        finishedAt,
+        sourceUrl,
+        createdAt: now,
+      });
+
+      const queueId = await ctx.db.insert("syncQueue", {
+        entityType: "initiative",
+        externalId,
+        payload,
+        status: "pending",
+        attempts: 0,
+        createdAt: now,
+      });
+
+      return {
+        success: true,
+        externalId,
+        localId,
+        queueId,
+      };
+    } catch (error) {
+      const errorMessage =
+        error && typeof error === "object" && "message" in error
+          ? (error.message as string)
+          : "Unknown error";
+
+      return {
+        success: false,
+        externalId: "",
+        localId: "" as Id<"initiatives">,
+        error: errorMessage,
+      };
+    }
+  },
+});
+
+// ============================================================================
+// LOCAL QUERY FUNCTIONS
+// ============================================================================
+
+/**
+ * Gets all local initiatives
+ */
+export const getAllInitiatives = query({
+  args: {},
+  returns: v.array(
+    v.object({
+      _id: v.id("initiatives"),
+      _creationTime: v.number(),
+      externalId: v.string(),
+      description: v.string(),
+      teamExternalId: v.string(),
+      riskExternalId: v.string(), // Required
+      assigneeExternalId: v.string(),
+      createdByExternalId: v.string(),
+      status: InitiativeStatusSchema, // Required
+      priority: PrioritySchema,
+      finishedAt: v.optional(v.number()),
+      slug: v.string(),
+      syncStatus: SyncStatusSchema,
+      createdAt: v.number(),
+      updatedAt: v.optional(v.number()),
+      deletedAt: v.optional(v.number()),
+    })
+  ),
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("initiatives")
+      .filter((q) => q.eq(q.field("deletedAt"), undefined))
+      .collect();
+  },
+});
+
+// ============================================================================
+// UPDATE MUTATIONS
+// ============================================================================
+
+/**
+ * Updates an initiative locally and queues for sync
+ * Resets syncStatus to "pending"
+ */
+export const updateInitiative = mutation({
+  args: {
+    externalId: v.string(),
+    description: v.optional(v.string()),
+    riskExternalId: v.optional(v.string()),
+    assigneeExternalId: v.optional(v.string()),
+    status: v.optional(InitiativeStatusSchema),
+    priority: v.optional(PrioritySchema),
+    finishedAt: v.optional(v.number()),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    externalId: v.string(),
+    queueId: v.optional(v.id("syncQueue")),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const {
+      externalId,
+      description,
+      riskExternalId,
+      assigneeExternalId,
+      status,
+      priority,
+      finishedAt,
+    } = args;
+
+    try {
+      // Find the initiative by externalId
+      const initiative = await ctx.db
+        .query("initiatives")
+        .withIndex("by_external_id", (q) => q.eq("externalId", externalId))
+        .first();
+
+      if (!initiative) {
+        return {
+          success: false,
+          externalId,
+          error: `Initiative not found: ${externalId}`,
+        };
+      }
+
+      // Validate external IDs if provided
+      if (riskExternalId) {
+        assertValidExternalId(riskExternalId, "riskExternalId");
+      }
+      if (assigneeExternalId) {
+        assertValidExternalId(assigneeExternalId, "assigneeExternalId");
+      }
+
+      const now = Date.now();
+
+      // Update the initiative
+      await ctx.db.patch(initiative._id, {
+        ...(description !== undefined && { description }),
+        ...(riskExternalId !== undefined && { riskExternalId }),
+        ...(assigneeExternalId !== undefined && { assigneeExternalId }),
+        ...(status !== undefined && { status }),
+        ...(priority !== undefined && { priority }),
+        ...(finishedAt !== undefined && { finishedAt }),
+        syncStatus: "pending",
+        updatedAt: now,
+      });
+
+      // Create payload for sync with updated values
+      const updatedInitiative = {
+        externalId,
+        description: description ?? initiative.description,
+        teamExternalId: initiative.teamExternalId,
+        riskExternalId: riskExternalId ?? initiative.riskExternalId,
+        assigneeExternalId: assigneeExternalId ?? initiative.assigneeExternalId,
+        createdByExternalId: initiative.createdByExternalId,
+        status: status ?? initiative.status,
+        priority: priority ?? initiative.priority,
+        finishedAt: finishedAt ?? initiative.finishedAt,
+        updatedAt: now,
+      };
+
+      const payload = JSON.stringify(updatedInitiative);
+
+      // Add to sync queue
+      const queueId = await ctx.db.insert("syncQueue", {
+        entityType: "initiative",
+        externalId,
+        payload,
+        status: "pending",
+        attempts: 0,
+        createdAt: now,
+      });
+
+      return {
+        success: true,
+        externalId,
+        queueId,
+      };
+    } catch (error) {
+      const errorMessage =
+        error && typeof error === "object" && "message" in error
+          ? (error.message as string)
+          : "Unknown error";
+
+      return {
+        success: false,
+        externalId,
+        error: errorMessage,
+      };
+    }
+  },
+});
+
+// ============================================================================
+// PUBLIC MUTATIONS - Entry points for consumers
+// ============================================================================
+
+/**
+ * Insert an initiative into LinkHub
+ */
+export const insertInitiative = mutation({
+  args: {
+    initiative: initiativePayloadValidator,
+  },
+  returns: v.object({
+    success: v.boolean(),
+    externalId: v.string(),
+    queueId: v.optional(v.id("syncQueue")),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const { initiative } = args;
+
+    // Validate external IDs
+    assertValidExternalId(initiative.externalId, "initiative.externalId");
+    assertValidExternalId(
+      initiative.teamExternalId,
+      "initiative.teamExternalId"
+    );
+    assertValidExternalId(
+      initiative.assigneeExternalId,
+      "initiative.assigneeExternalId"
+    );
+    assertValidExternalId(
+      initiative.createdByExternalId,
+      "initiative.createdByExternalId"
+    );
+    assertValidExternalId(
+      initiative.riskExternalId,
+      "initiative.riskExternalId"
+    );
+
+    // Add to sync queue
+    const payload = JSON.stringify(initiative);
+    const queueId = await ctx.db.insert("syncQueue", {
+      entityType: "initiative",
+      externalId: initiative.externalId,
+      payload,
+      status: "pending",
+      attempts: 0,
+      createdAt: Date.now(),
+    });
+
+    return {
+      success: true,
+      externalId: initiative.externalId,
+      queueId,
+    };
+  },
+});

package/src/component/entities/keyResults.ts

@@ -0,0 +1,334 @@
+/**
+ * Key Results Entity for OKRHub Component
+ *
+ * CRUD operations and queries for Key Results.
+ */
+
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server.js";
+import type { Id } from "../_generated/dataModel.js";
+import { generateExternalId } from "../externalId.js";
+import { assertValidExternalId, generateSlug } from "../lib/validation.js";
+import { keyResultPayloadValidator, SyncStatusSchema } from "../schema.js";
+
+// ============================================================================
+// LOCAL CRUD MUTATIONS
+// ============================================================================
+
+/**
+ * Creates a key result locally and queues for sync
+ * Note: weight is always set to 0, managed only by linkhub
+ */
+export const createKeyResult = mutation({
+  args: {
+    sourceApp: v.string(),
+    sourceUrl: v.optional(v.string()),
+    objectiveExternalId: v.string(), // Required: Reference to objective
+    indicatorExternalId: v.string(),
+    teamExternalId: v.string(),
+    forecastValue: v.optional(v.number()),
+    targetValue: v.optional(v.number()),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    externalId: v.string(),
+    localId: v.id("keyResults"),
+    queueId: v.optional(v.id("syncQueue")),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const {
+      sourceApp,
+      sourceUrl,
+      objectiveExternalId,
+      indicatorExternalId,
+      teamExternalId,
+      forecastValue,
+      targetValue,
+    } = args;
+
+    try {
+      // Validate external IDs
+      assertValidExternalId(teamExternalId, "teamExternalId");
+      assertValidExternalId(indicatorExternalId, "indicatorExternalId");
+      assertValidExternalId(objectiveExternalId, "objectiveExternalId");
+
+      const externalId = generateExternalId(sourceApp, "keyResult");
+      const slug = generateSlug(sourceApp, `kr-${sourceApp}`);
+      const now = Date.now();
+
+      // Save locally
+      const localId = await ctx.db.insert("keyResults", {
+        externalId,
+        objectiveExternalId,
+        indicatorExternalId,
+        teamExternalId,
+        forecastValue,
+        targetValue,
+        slug,
+        syncStatus: "pending",
+        createdAt: now,
+      });
+
+      // Create payload for sync (weight=0 always)
+      const payload = JSON.stringify({
+        externalId,
+        objectiveExternalId,
+        indicatorExternalId,
+        teamExternalId,
+        weight: 0, // Always 0, managed by linkhub
+        forecastValue,
+        targetValue,
+        sourceUrl,
+        createdAt: now,
+      });
+
+      const queueId = await ctx.db.insert("syncQueue", {
+        entityType: "keyResult",
+        externalId,
+        payload,
+        status: "pending",
+        attempts: 0,
+        createdAt: now,
+      });
+
+      return {
+        success: true,
+        externalId,
+        localId,
+        queueId,
+      };
+    } catch (error) {
+      const errorMessage =
+        error && typeof error === "object" && "message" in error
+          ? (error.message as string)
+          : "Unknown error";
+
+      return {
+        success: false,
+        externalId: "",
+        localId: "" as Id<"keyResults">,
+        error: errorMessage,
+      };
+    }
+  },
+});
+
+// ============================================================================
+// LOCAL QUERY FUNCTIONS
+// ============================================================================
+
+/**
+ * Gets all local key results for an objective
+ */
+export const getKeyResultsByObjective = query({
+  args: {
+    objectiveExternalId: v.string(),
+  },
+  returns: v.array(
+    v.object({
+      _id: v.id("keyResults"),
+      _creationTime: v.number(),
+      externalId: v.string(),
+      objectiveExternalId: v.string(), // Required
+      indicatorExternalId: v.string(),
+      teamExternalId: v.string(),
+      forecastValue: v.optional(v.number()),
+      targetValue: v.optional(v.number()),
+      slug: v.string(),
+      syncStatus: SyncStatusSchema,
+      createdAt: v.number(),
+      updatedAt: v.optional(v.number()),
+      deletedAt: v.optional(v.number()),
+    })
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("keyResults")
+      .withIndex("by_objective", (q) =>
+        q.eq("objectiveExternalId", args.objectiveExternalId)
+      )
+      .filter((q) => q.eq(q.field("deletedAt"), undefined))
+      .collect();
+  },
+});
+
+/**
+ * Gets all local key results
+ */
+export const getAllKeyResults = query({
+  args: {},
+  returns: v.array(
+    v.object({
+      _id: v.id("keyResults"),
+      _creationTime: v.number(),
+      externalId: v.string(),
+      objectiveExternalId: v.string(), // Required
+      indicatorExternalId: v.string(),
+      teamExternalId: v.string(),
+      forecastValue: v.optional(v.number()),
+      targetValue: v.optional(v.number()),
+      slug: v.string(),
+      syncStatus: SyncStatusSchema,
+      createdAt: v.number(),
+      updatedAt: v.optional(v.number()),
+      deletedAt: v.optional(v.number()),
+    })
+  ),
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("keyResults")
+      .filter((q) => q.eq(q.field("deletedAt"), undefined))
+      .collect();
+  },
+});
+
+// ============================================================================
+// UPDATE MUTATIONS
+// ============================================================================
+
+/**
+ * Updates a key result locally and queues for sync
+ * Resets syncStatus to "pending"
+ */
+export const updateKeyResult = mutation({
+  args: {
+    externalId: v.string(),
+    objectiveExternalId: v.optional(v.string()),
+    forecastValue: v.optional(v.number()),
+    targetValue: v.optional(v.number()),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    externalId: v.string(),
+    queueId: v.optional(v.id("syncQueue")),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const { externalId, objectiveExternalId, forecastValue, targetValue } = args;
+
+    try {
+      // Find the key result by externalId
+      const keyResult = await ctx.db
+        .query("keyResults")
+        .withIndex("by_external_id", (q) => q.eq("externalId", externalId))
+        .first();
+
+      if (!keyResult) {
+        return {
+          success: false,
+          externalId,
+          error: `Key result not found: ${externalId}`,
+        };
+      }
+
+      // Validate objectiveExternalId if provided
+      if (objectiveExternalId) {
+        assertValidExternalId(objectiveExternalId, "objectiveExternalId");
+      }
+
+      const now = Date.now();
+
+      // Update the key result
+      await ctx.db.patch(keyResult._id, {
+        ...(objectiveExternalId !== undefined && { objectiveExternalId }),
+        ...(forecastValue !== undefined && { forecastValue }),
+        ...(targetValue !== undefined && { targetValue }),
+        syncStatus: "pending",
+        updatedAt: now,
+      });
+
+      // Create payload for sync with updated values
+      const updatedKeyResult = {
+        externalId,
+        objectiveExternalId: objectiveExternalId ?? keyResult.objectiveExternalId,
+        indicatorExternalId: keyResult.indicatorExternalId,
+        teamExternalId: keyResult.teamExternalId,
+        weight: 0, // Always 0, managed by LinkHub
+        forecastValue: forecastValue ?? keyResult.forecastValue,
+        targetValue: targetValue ?? keyResult.targetValue,
+        updatedAt: now,
+      };
+
+      const payload = JSON.stringify(updatedKeyResult);
+
+      // Add to sync queue
+      const queueId = await ctx.db.insert("syncQueue", {
+        entityType: "keyResult",
+        externalId,
+        payload,
+        status: "pending",
+        attempts: 0,
+        createdAt: now,
+      });
+
+      return {
+        success: true,
+        externalId,
+        queueId,
+      };
+    } catch (error) {
+      const errorMessage =
+        error && typeof error === "object" && "message" in error
+          ? (error.message as string)
+          : "Unknown error";
+
+      return {
+        success: false,
+        externalId,
+        error: errorMessage,
+      };
+    }
+  },
+});
+
+// ============================================================================
+// PUBLIC MUTATIONS - Entry points for consumers
+// ============================================================================
+
+/**
+ * Insert a key result into LinkHub
+ */
+export const insertKeyResult = mutation({
+  args: {
+    keyResult: keyResultPayloadValidator,
+  },
+  returns: v.object({
+    success: v.boolean(),
+    externalId: v.string(),
+    queueId: v.optional(v.id("syncQueue")),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const { keyResult } = args;
+
+    // Validate external IDs
+    assertValidExternalId(keyResult.externalId, "keyResult.externalId");
+    assertValidExternalId(keyResult.teamExternalId, "keyResult.teamExternalId");
+    assertValidExternalId(
+      keyResult.indicatorExternalId,
+      "keyResult.indicatorExternalId"
+    );
+    assertValidExternalId(
+      keyResult.objectiveExternalId,
+      "keyResult.objectiveExternalId"
+    );
+
+    // Add to sync queue
+    const payload = JSON.stringify(keyResult);
+    const queueId = await ctx.db.insert("syncQueue", {
+      entityType: "keyResult",
+      externalId: keyResult.externalId,
+      payload,
+      status: "pending",
+      attempts: 0,
+      createdAt: Date.now(),
+    });
+
+    return {
+      success: true,
+      externalId: keyResult.externalId,
+      queueId,
+    };
+  },
+});