@okrlinkhub/okrhub 0.1.0

package/src/component/entities/risks.ts

@@ -0,0 +1,383 @@
+/**
+ * Risks Entity for OKRHub Component
+ *
+ * CRUD operations and queries for Risks.
+ */
+
+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 {
+  riskPayloadValidator,
+  PrioritySchema,
+  SyncStatusSchema,
+} from "../schema.js";
+
+// ============================================================================
+// LOCAL CRUD MUTATIONS
+// ============================================================================
+
+/**
+ * Creates a risk locally and queues for sync
+ */
+export const createRisk = mutation({
+  args: {
+    sourceApp: v.string(),
+    sourceUrl: v.optional(v.string()),
+    description: v.string(),
+    teamExternalId: v.string(),
+    keyResultExternalId: v.string(), // Required: Reference to key result
+    priority: PrioritySchema,
+    indicatorExternalId: v.optional(v.string()),
+    triggerValue: v.optional(v.number()),
+    triggeredIfLower: v.optional(v.boolean()),
+    useForecastAsTrigger: v.optional(v.boolean()),
+    isRed: v.optional(v.boolean()),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    externalId: v.string(),
+    localId: v.id("risks"),
+    queueId: v.optional(v.id("syncQueue")),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const {
+      sourceApp,
+      sourceUrl,
+      description,
+      teamExternalId,
+      keyResultExternalId,
+      priority,
+      indicatorExternalId,
+      triggerValue,
+      triggeredIfLower,
+      useForecastAsTrigger,
+      isRed,
+    } = args;
+
+    try {
+      assertValidExternalId(teamExternalId, "teamExternalId");
+      assertValidExternalId(keyResultExternalId, "keyResultExternalId");
+      if (indicatorExternalId) {
+        assertValidExternalId(indicatorExternalId, "indicatorExternalId");
+      }
+
+      const externalId = generateExternalId(sourceApp, "risk");
+      const slug = generateSlug(sourceApp, description.substring(0, 30));
+      const now = Date.now();
+
+      const localId = await ctx.db.insert("risks", {
+        externalId,
+        description,
+        teamExternalId,
+        keyResultExternalId,
+        priority,
+        indicatorExternalId,
+        triggerValue,
+        triggeredIfLower,
+        useForecastAsTrigger,
+        isRed,
+        slug,
+        syncStatus: "pending",
+        createdAt: now,
+      });
+
+      const payload = JSON.stringify({
+        externalId,
+        description,
+        teamExternalId,
+        keyResultExternalId,
+        priority,
+        indicatorExternalId,
+        triggerValue,
+        triggeredIfLower,
+        useForecastAsTrigger,
+        isRed,
+        sourceUrl,
+        createdAt: now,
+      });
+
+      const queueId = await ctx.db.insert("syncQueue", {
+        entityType: "risk",
+        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<"risks">,
+        error: errorMessage,
+      };
+    }
+  },
+});
+
+// ============================================================================
+// LOCAL QUERY FUNCTIONS
+// ============================================================================
+
+/**
+ * Gets all local risks for a key result
+ */
+export const getRisksByKeyResult = query({
+  args: {
+    keyResultExternalId: v.string(),
+  },
+  returns: v.array(
+    v.object({
+      _id: v.id("risks"),
+      _creationTime: v.number(),
+      externalId: v.string(),
+      description: v.string(),
+      teamExternalId: v.string(),
+      keyResultExternalId: v.string(), // Required
+      priority: PrioritySchema,
+      indicatorExternalId: v.optional(v.string()),
+      triggerValue: v.optional(v.number()),
+      triggeredIfLower: v.optional(v.boolean()),
+      useForecastAsTrigger: v.optional(v.boolean()),
+      isRed: v.optional(v.boolean()),
+      slug: v.string(),
+      syncStatus: SyncStatusSchema,
+      createdAt: v.number(),
+      deletedAt: v.optional(v.number()),
+    })
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("risks")
+      .withIndex("by_key_result", (q) =>
+        q.eq("keyResultExternalId", args.keyResultExternalId)
+      )
+      .filter((q) => q.eq(q.field("deletedAt"), undefined))
+      .collect();
+  },
+});
+
+/**
+ * Gets all local risks
+ */
+export const getAllRisks = query({
+  args: {},
+  returns: v.array(
+    v.object({
+      _id: v.id("risks"),
+      _creationTime: v.number(),
+      externalId: v.string(),
+      description: v.string(),
+      teamExternalId: v.string(),
+      keyResultExternalId: v.string(), // Required
+      priority: PrioritySchema,
+      indicatorExternalId: v.optional(v.string()),
+      triggerValue: v.optional(v.number()),
+      triggeredIfLower: v.optional(v.boolean()),
+      useForecastAsTrigger: v.optional(v.boolean()),
+      isRed: v.optional(v.boolean()),
+      slug: v.string(),
+      syncStatus: SyncStatusSchema,
+      createdAt: v.number(),
+      deletedAt: v.optional(v.number()),
+    })
+  ),
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("risks")
+      .filter((q) => q.eq(q.field("deletedAt"), undefined))
+      .collect();
+  },
+});
+
+// ============================================================================
+// UPDATE MUTATIONS
+// ============================================================================
+
+/**
+ * Updates a risk locally and queues for sync
+ * Resets syncStatus to "pending"
+ */
+export const updateRisk = mutation({
+  args: {
+    externalId: v.string(),
+    description: v.optional(v.string()),
+    priority: v.optional(PrioritySchema),
+    keyResultExternalId: v.optional(v.string()),
+    indicatorExternalId: v.optional(v.string()),
+    triggerValue: v.optional(v.number()),
+    triggeredIfLower: v.optional(v.boolean()),
+    useForecastAsTrigger: v.optional(v.boolean()),
+    isRed: v.optional(v.boolean()),
+  },
+  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,
+      priority,
+      keyResultExternalId,
+      indicatorExternalId,
+      triggerValue,
+      triggeredIfLower,
+      useForecastAsTrigger,
+      isRed,
+    } = args;
+
+    try {
+      // Find the risk by externalId
+      const risk = await ctx.db
+        .query("risks")
+        .withIndex("by_external_id", (q) => q.eq("externalId", externalId))
+        .first();
+
+      if (!risk) {
+        return {
+          success: false,
+          externalId,
+          error: `Risk not found: ${externalId}`,
+        };
+      }
+
+      // Validate external IDs if provided
+      if (keyResultExternalId) {
+        assertValidExternalId(keyResultExternalId, "keyResultExternalId");
+      }
+      if (indicatorExternalId) {
+        assertValidExternalId(indicatorExternalId, "indicatorExternalId");
+      }
+
+      const now = Date.now();
+
+      // Update the risk
+      await ctx.db.patch(risk._id, {
+        ...(description !== undefined && { description }),
+        ...(priority !== undefined && { priority }),
+        ...(keyResultExternalId !== undefined && { keyResultExternalId }),
+        ...(indicatorExternalId !== undefined && { indicatorExternalId }),
+        ...(triggerValue !== undefined && { triggerValue }),
+        ...(triggeredIfLower !== undefined && { triggeredIfLower }),
+        ...(useForecastAsTrigger !== undefined && { useForecastAsTrigger }),
+        ...(isRed !== undefined && { isRed }),
+        syncStatus: "pending",
+      });
+
+      // Create payload for sync with updated values
+      const updatedRisk = {
+        externalId,
+        description: description ?? risk.description,
+        teamExternalId: risk.teamExternalId,
+        priority: priority ?? risk.priority,
+        keyResultExternalId: keyResultExternalId ?? risk.keyResultExternalId,
+        indicatorExternalId: indicatorExternalId ?? risk.indicatorExternalId,
+        triggerValue: triggerValue ?? risk.triggerValue,
+        triggeredIfLower: triggeredIfLower ?? risk.triggeredIfLower,
+        useForecastAsTrigger: useForecastAsTrigger ?? risk.useForecastAsTrigger,
+        isRed: isRed ?? risk.isRed,
+      };
+
+      const payload = JSON.stringify(updatedRisk);
+
+      // Add to sync queue
+      const queueId = await ctx.db.insert("syncQueue", {
+        entityType: "risk",
+        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 risk into LinkHub
+ */
+export const insertRisk = mutation({
+  args: {
+    risk: riskPayloadValidator,
+  },
+  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 { risk } = args;
+
+    // Validate external IDs
+    assertValidExternalId(risk.externalId, "risk.externalId");
+    assertValidExternalId(risk.teamExternalId, "risk.teamExternalId");
+    assertValidExternalId(
+      risk.keyResultExternalId,
+      "risk.keyResultExternalId"
+    );
+    if (risk.indicatorExternalId) {
+      assertValidExternalId(
+        risk.indicatorExternalId,
+        "risk.indicatorExternalId"
+      );
+    }
+
+    // Add to sync queue
+    const payload = JSON.stringify(risk);
+    const queueId = await ctx.db.insert("syncQueue", {
+      entityType: "risk",
+      externalId: risk.externalId,
+      payload,
+      status: "pending",
+      attempts: 0,
+      createdAt: Date.now(),
+    });
+
+    return {
+      success: true,
+      externalId: risk.externalId,
+      queueId,
+    };
+  },
+});

package/src/component/externalId.ts

@@ -0,0 +1,172 @@
+/**
+ * External ID helper for OKRHub component
+ *
+ * External IDs are used to map entities between the consumer app and LinkHub.
+ * Format: {sourceApp}:{entityType}:{uuid}
+ *
+ * Example: "mycrm:objective:550e8400-e29b-41d4-a716-446655440000"
+ */
+
+import { v } from "convex/values";
+
+// Entity types supported by OKRHub
+export const ENTITY_TYPES = [
+  "objective",
+  "keyResult",
+  "risk",
+  "initiative",
+  "indicator",
+  "indicatorValue",
+  "indicatorForecast",
+  "milestone",
+  "team",
+  "company",
+  "user",
+] as const;
+
+export type EntityType = (typeof ENTITY_TYPES)[number];
+
+// Convex validator for entity type
+export const entityTypeValidator = v.union(
+  v.literal("objective"),
+  v.literal("keyResult"),
+  v.literal("risk"),
+  v.literal("initiative"),
+  v.literal("indicator"),
+  v.literal("indicatorValue"),
+  v.literal("indicatorForecast"),
+  v.literal("milestone"),
+  v.literal("team"),
+  v.literal("company"),
+  v.literal("user")
+);
+
+// Regex pattern for external ID validation
+// Format: {sourceApp}:{entityType}:{uuid}
+// - sourceApp: 2-32 lowercase alphanumeric characters or hyphens
+// - entityType: one of the supported entity types
+// - uuid: UUID v4 format (36 characters with hyphens)
+const EXTERNAL_ID_REGEX =
+  /^[a-z0-9-]{2,32}:(objective|keyResult|risk|initiative|indicator|indicatorValue|indicatorForecast|milestone|team|company|user):[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+
+// Simpler regex for basic validation (allows any UUID-like format)
+const EXTERNAL_ID_REGEX_SIMPLE =
+  /^[a-z0-9-]{2,32}:(objective|keyResult|risk|initiative|indicator|indicatorValue|indicatorForecast|milestone|team|company|user):[a-f0-9-]{36}$/;
+
+/**
+ * Validates an external ID format
+ * @param id - The external ID to validate
+ * @returns true if the ID is valid, false otherwise
+ */
+export function validateExternalId(id: string): boolean {
+  return EXTERNAL_ID_REGEX_SIMPLE.test(id);
+}
+
+/**
+ * Validates a source app name format
+ * @param sourceApp - The source app name to validate
+ * @returns true if valid, false otherwise
+ */
+export function validateSourceApp(sourceApp: string): boolean {
+  return /^[a-z0-9-]{2,32}$/.test(sourceApp);
+}
+
+/**
+ * Generates a new external ID for the given source app and entity type
+ * @param sourceApp - The identifier of the source application (2-32 lowercase alphanumeric or hyphens)
+ * @param entityType - The type of entity (objective, keyResult, risk, initiative, indicator, milestone)
+ * @returns A new external ID in the format {sourceApp}:{entityType}:{uuid}
+ * @throws Error if sourceApp format is invalid
+ */
+export function generateExternalId(
+  sourceApp: string,
+  entityType: EntityType
+): string {
+  if (!validateSourceApp(sourceApp)) {
+    throw new Error(
+      `Invalid sourceApp format: "${sourceApp}". Must be 2-32 lowercase alphanumeric characters or hyphens.`
+    );
+  }
+
+  const uuid = crypto.randomUUID();
+  return `${sourceApp}:${entityType}:${uuid}`;
+}
+
+/**
+ * Parsed external ID structure
+ */
+export interface ParsedExternalId {
+  sourceApp: string;
+  entityType: EntityType;
+  uuid: string;
+}
+
+/**
+ * Parses an external ID into its components
+ * @param id - The external ID to parse
+ * @returns The parsed components, or null if the ID is invalid
+ */
+export function parseExternalId(id: string): ParsedExternalId | null {
+  const match = id.match(
+    /^([a-z0-9-]{2,32}):(objective|keyResult|risk|initiative|indicator|indicatorValue|indicatorForecast|milestone|team|company|user):([a-f0-9-]{36})$/
+  );
+
+  if (!match) return null;
+
+  return {
+    sourceApp: match[1],
+    entityType: match[2] as EntityType,
+    uuid: match[3],
+  };
+}
+
+/**
+ * Extracts the source app from an external ID
+ * @param id - The external ID
+ * @returns The source app, or null if invalid
+ */
+export function extractSourceApp(id: string): string | null {
+  const parsed = parseExternalId(id);
+  return parsed?.sourceApp ?? null;
+}
+
+/**
+ * Extracts the entity type from an external ID
+ * @param id - The external ID
+ * @returns The entity type, or null if invalid
+ */
+export function extractEntityType(id: string): EntityType | null {
+  const parsed = parseExternalId(id);
+  return parsed?.entityType ?? null;
+}
+
+/**
+ * Checks if two external IDs belong to the same source app
+ * @param id1 - First external ID
+ * @param id2 - Second external ID
+ * @returns true if both IDs are from the same source app
+ */
+export function sameSourceApp(id1: string, id2: string): boolean {
+  const app1 = extractSourceApp(id1);
+  const app2 = extractSourceApp(id2);
+  return app1 !== null && app1 === app2;
+}
+
+/**
+ * Convex validator for external ID (as string with runtime validation)
+ * Use this in your mutation/query args
+ */
+export const externalIdValidator = v.string();
+
+/**
+ * Version information for the OKRHub component
+ * Used for compatibility checks with LinkHub API
+ */
+export const OKRHUB_VERSION = "0.1.0";
+
+/**
+ * Gets the current component version
+ */
+export function getVersion(): string {
+  return OKRHUB_VERSION;
+}

package/src/component/lib/hmac.ts

@@ -0,0 +1,53 @@
+/**
+ * HMAC Signature Utilities for OKRHub Component
+ *
+ * Provides cryptographic signature functions for secure API communication
+ * with LinkHub's ingest endpoints.
+ */
+
+import { OKRHUB_VERSION } from "../externalId.js";
+
+/**
+ * Creates HMAC-SHA256 signature for payload authentication
+ *
+ * SECURITY NOTE: Uses the signing secret (not the API key) to create
+ * cryptographically consistent signatures that the server can verify.
+ */
+export async function createHmacSignature(
+  payload: string,
+  signingSecret: string
+): Promise<string> {
+  const encoder = new TextEncoder();
+  const keyData = encoder.encode(signingSecret);
+  const messageData = encoder.encode(payload);
+
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+
+  const signature = await crypto.subtle.sign("HMAC", cryptoKey, messageData);
+  const hashArray = Array.from(new Uint8Array(signature));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Creates request headers with HMAC signature, version, and key prefix
+ */
+export async function createRequestHeaders(
+  payload: string,
+  apiKeyPrefix: string,
+  signingSecret: string
+): Promise<Headers> {
+  const signature = await createHmacSignature(payload, signingSecret);
+
+  return new Headers({
+    "Content-Type": "application/json",
+    "X-OKRHub-Version": OKRHUB_VERSION,
+    "X-OKRHub-Key-Prefix": apiKeyPrefix,
+    "X-OKRHub-Signature": signature,
+  });
+}

package/src/component/lib/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Library utilities barrel export
+ */
+
+export { createHmacSignature, createRequestHeaders } from "./hmac.js";
+export { assertValidExternalId, generateSlug } from "./validation.js";
+export type { IngestResponse, BatchIngestResponse } from "./types.js";

package/src/component/lib/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared Types for OKRHub Component
+ *
+ * Response types and shared interfaces used across the component.
+ */
+
+/**
+ * Response from LinkHub's single entity ingest endpoint
+ */
+export interface IngestResponse {
+  success: boolean;
+  externalId: string;
+  linkHubId?: string;
+  action: "create" | "update";
+  error?: string;
+}
+
+/**
+ * Response from LinkHub's batch ingest endpoint
+ */
+export interface BatchIngestResponse {
+  success: boolean;
+  results: {
+    entityType: string;
+    externalId: string;
+    linkHubId?: string;
+    action: "create" | "update";
+    error?: string;
+  }[];
+  errors: string[];
+}

package/src/component/lib/validation.ts

@@ -0,0 +1,41 @@
+/**
+ * Validation Utilities for OKRHub Component
+ *
+ * Provides validation helpers for external IDs and slug generation.
+ */
+
+import { validateExternalId } from "../externalId.js";
+
+/**
+ * Validates external ID format and throws if invalid
+ */
+export function assertValidExternalId(
+  externalId: string,
+  fieldName = "externalId"
+): void {
+  if (!validateExternalId(externalId)) {
+    throw new Error(
+      `Invalid ${fieldName} format: "${externalId}". ` +
+        `Expected format: {sourceApp}:{entityType}:{uuid}`
+    );
+  }
+}
+
+/**
+ * Generates a slug from text with sourceApp prefix
+ * Pattern: {sourceApp}-{baseSlug}-{suffix}
+ */
+export function generateSlug(
+  sourceApp: string,
+  text: string,
+  maxLength = 50
+): string {
+  const baseSlug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .substring(0, maxLength - sourceApp.length - 7); // Reserve space for prefix and suffix
+
+  const suffix = Math.random().toString(36).substring(2, 6);
+  return `${sourceApp}-${baseSlug}-${suffix}`;
+}