@okrlinkhub/okrhub 0.1.0

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.ts

@@ -0,0 +1,156 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("okrhub");

package/src/component/entities/batch.ts

@@ -0,0 +1,90 @@
+/**
+ * Batch Operations for OKRHub Component
+ *
+ * Batch insert mutation for multiple entities.
+ */
+
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import type { Id } from "../_generated/dataModel.js";
+import type { EntityType } from "../externalId.js";
+import { assertValidExternalId } from "../lib/validation.js";
+import { batchPayloadValidator, type BatchPayload } from "../schema.js";
+
+// ============================================================================
+// BATCH MUTATIONS
+// ============================================================================
+
+/**
+ * Insert a batch of entities into LinkHub
+ */
+export const insertBatch = mutation({
+  args: {
+    batch: batchPayloadValidator,
+  },
+  returns: v.object({
+    success: v.boolean(),
+    queueIds: v.array(v.id("syncQueue")),
+    errors: v.array(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const { batch } = args;
+    const queueIds: Id<"syncQueue">[] = [];
+    const errors: string[] = [];
+
+    // Process each entity type
+    const entityTypes: { key: keyof BatchPayload; type: EntityType }[] = [
+      { key: "companies", type: "objective" }, // Using objective as placeholder
+      { key: "teams", type: "objective" },
+      { key: "users", type: "objective" },
+      { key: "indicators", type: "indicator" },
+      { key: "objectives", type: "objective" },
+      { key: "keyResults", type: "keyResult" },
+      { key: "risks", type: "risk" },
+      { key: "initiatives", type: "initiative" },
+      { key: "milestones", type: "milestone" },
+      { key: "indicatorValues", type: "indicator" },
+      { key: "indicatorForecasts", type: "indicator" },
+    ];
+
+    for (const { key, type: _type } of entityTypes) {
+      const items = batch[key];
+      if (!items || items.length === 0) continue;
+
+      for (const item of items) {
+        try {
+          // Validate external ID
+          if ("externalId" in item && typeof item.externalId === "string") {
+            assertValidExternalId(item.externalId);
+          }
+
+          const payload = JSON.stringify(item);
+          const queueId = await ctx.db.insert("syncQueue", {
+            entityType: key,
+            externalId:
+              "externalId" in item && typeof item.externalId === "string"
+                ? item.externalId
+                : `batch-${Date.now()}`,
+            payload,
+            status: "pending",
+            attempts: 0,
+            createdAt: Date.now(),
+          });
+          queueIds.push(queueId);
+        } catch (error) {
+          const errorMessage =
+            error && typeof error === "object" && "message" in error
+              ? (error.message as string)
+              : "Unknown error";
+          errors.push(`${key}: ${errorMessage}`);
+        }
+      }
+    }
+
+    return {
+      success: errors.length === 0,
+      queueIds,
+      errors,
+    };
+  },
+});

package/src/component/entities/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Entities barrel export
+ */
+
+// Objectives
+export {
+  createObjective,
+  getObjectivesByTeam,
+  getAllObjectives,
+  insertObjective,
+} from "./objectives.js";
+
+// Key Results
+export {
+  createKeyResult,
+  getKeyResultsByObjective,
+  getAllKeyResults,
+  insertKeyResult,
+} from "./keyResults.js";
+
+// Risks
+export {
+  createRisk,
+  getRisksByKeyResult,
+  getAllRisks,
+  insertRisk,
+} from "./risks.js";
+
+// Initiatives
+export {
+  createInitiative,
+  getAllInitiatives,
+  insertInitiative,
+} from "./initiatives.js";
+
+// Indicators
+export {
+  createIndicator,
+  getAllIndicators,
+  insertIndicator,
+} from "./indicators.js";
+
+// Indicator Values
+export {
+  createIndicatorValue,
+  getAllIndicatorValues,
+  insertIndicatorValue,
+} from "./indicatorValues.js";
+
+// Indicator Forecasts
+export {
+  createIndicatorForecast,
+  getAllIndicatorForecasts,
+} from "./indicatorForecasts.js";
+
+// Milestones
+export {
+  createMilestone,
+  getAllMilestones,
+  insertMilestone,
+} from "./milestones.js";
+
+// Batch
+export { insertBatch } from "./batch.js";

package/src/component/entities/indicatorForecasts.ts

@@ -0,0 +1,205 @@
+/**
+ * Indicator Forecasts Entity for OKRHub Component
+ *
+ * CRUD operations and queries for Indicator Forecasts.
+ */
+
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server.js";
+import type { Id } from "../_generated/dataModel.js";
+import { assertValidExternalId } from "../lib/validation.js";
+import { SyncStatusSchema } from "../schema.js";
+
+// ============================================================================
+// LOCAL CRUD MUTATIONS
+// ============================================================================
+
+/**
+ * Creates an indicator forecast locally and queues for sync
+ */
+export const createIndicatorForecast = mutation({
+  args: {
+    sourceApp: v.string(),
+    sourceUrl: v.optional(v.string()),
+    indicatorExternalId: v.string(),
+    value: v.number(),
+    date: v.number(),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    externalId: v.string(),
+    localId: v.id("indicatorForecasts"),
+    queueId: v.optional(v.id("syncQueue")),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const { sourceApp, sourceUrl, indicatorExternalId, value, date } = args;
+
+    try {
+      assertValidExternalId(indicatorExternalId, "indicatorExternalId");
+
+      const uuid = crypto.randomUUID();
+      const externalId = `${sourceApp}:indicatorForecast:${uuid}`;
+      const now = Date.now();
+
+      const localId = await ctx.db.insert("indicatorForecasts", {
+        externalId,
+        indicatorExternalId,
+        value,
+        date,
+        syncStatus: "pending",
+        createdAt: now,
+      });
+
+      const payload = JSON.stringify({
+        externalId,
+        indicatorExternalId,
+        value,
+        date,
+        sourceUrl,
+        createdAt: now,
+      });
+
+      const queueId = await ctx.db.insert("syncQueue", {
+        entityType: "indicatorForecast",
+        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<"indicatorForecasts">,
+        error: errorMessage,
+      };
+    }
+  },
+});
+
+// ============================================================================
+// LOCAL QUERY FUNCTIONS
+// ============================================================================
+
+// ============================================================================
+// UPDATE MUTATIONS
+// ============================================================================
+
+/**
+ * Updates an indicator forecast locally and queues for sync
+ * Resets syncStatus to "pending"
+ */
+export const updateIndicatorForecast = mutation({
+  args: {
+    externalId: v.string(),
+    value: v.optional(v.number()),
+    date: 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, value, date } = args;
+
+    try {
+      // Find the indicator forecast by externalId
+      const indicatorForecast = await ctx.db
+        .query("indicatorForecasts")
+        .withIndex("by_external_id", (q) => q.eq("externalId", externalId))
+        .first();
+
+      if (!indicatorForecast) {
+        return {
+          success: false,
+          externalId,
+          error: `Indicator forecast not found: ${externalId}`,
+        };
+      }
+
+      const now = Date.now();
+
+      // Update the indicator forecast
+      await ctx.db.patch(indicatorForecast._id, {
+        ...(value !== undefined && { value }),
+        ...(date !== undefined && { date }),
+        syncStatus: "pending",
+      });
+
+      // Create payload for sync with updated values
+      const updatedIndicatorForecast = {
+        externalId,
+        indicatorExternalId: indicatorForecast.indicatorExternalId,
+        value: value ?? indicatorForecast.value,
+        date: date ?? indicatorForecast.date,
+      };
+
+      const payload = JSON.stringify(updatedIndicatorForecast);
+
+      // Add to sync queue
+      const queueId = await ctx.db.insert("syncQueue", {
+        entityType: "indicatorForecast",
+        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,
+      };
+    }
+  },
+});
+
+/**
+ * Gets all local indicator forecasts
+ */
+export const getAllIndicatorForecasts = query({
+  args: {},
+  returns: v.array(
+    v.object({
+      _id: v.id("indicatorForecasts"),
+      _creationTime: v.number(),
+      externalId: v.string(),
+      indicatorExternalId: v.string(),
+      value: v.number(),
+      date: v.number(),
+      syncStatus: SyncStatusSchema,
+      createdAt: v.number(),
+    })
+  ),
+  handler: async (ctx) => {
+    return await ctx.db.query("indicatorForecasts").collect();
+  },
+});