@open-skills-hub/api 1.0.0

package/src/controllers/cache.ts

@@ -0,0 +1,344 @@
+/**
+ * Open Skills Hub - Cache Controller
+ */
+
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import {
+  getStorage,
+  getConfig,
+  generateUUID,
+  now,
+  calculateExpiry,
+  buildSkillFullName,
+  parseSkillFullName,
+  AppError,
+  ErrorCodes,
+} from '@open-skills-hub/core';
+import type { CacheMetadata, AuditLog } from '@open-skills-hub/core';
+import { sendSuccess } from '../middleware/error.js';
+import { logger } from '../middleware/logger.js';
+import type {
+  SkillNameParam,
+  SkillVersionParam,
+} from '../middleware/validation.js';
+
+/**
+ * Get all cached skills
+ */
+export async function getCachedSkills(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const cacheEntries = await storage.getAllCacheMetadata();
+
+  // Group by skill name
+  const bySkill: Record<string, {
+    skillName: string;
+    versions: {
+      version: string;
+      cachedAt: string;
+      expiresAt?: string;
+      size?: number;
+      hitCount: number;
+      lastHitAt?: string;
+    }[];
+    totalHits: number;
+    totalSize: number;
+  }> = {};
+
+  for (const entry of cacheEntries) {
+    if (!bySkill[entry.skillName]) {
+      bySkill[entry.skillName] = {
+        skillName: entry.skillName,
+        versions: [],
+        totalHits: 0,
+        totalSize: 0,
+      };
+    }
+
+    bySkill[entry.skillName]!.versions.push({
+      version: entry.version,
+      cachedAt: entry.cachedAt,
+      expiresAt: entry.expiresAt,
+      size: entry.size,
+      hitCount: entry.hitCount,
+      lastHitAt: entry.lastHitAt,
+    });
+
+    bySkill[entry.skillName]!.totalHits += entry.hitCount;
+    bySkill[entry.skillName]!.totalSize += entry.size ?? 0;
+  }
+
+  const skills = Object.values(bySkill).sort((a, b) => b.totalHits - a.totalHits);
+
+  sendSuccess(request, reply, {
+    count: cacheEntries.length,
+    skills,
+  });
+}
+
+/**
+ * Get cache info for a specific skill
+ */
+export async function getSkillCacheInfo(
+  request: FastifyRequest<{ Params: SkillNameParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const allCache = await storage.getAllCacheMetadata();
+  const skillCache = allCache.filter(c => c.skillName === fullName);
+
+  if (skillCache.length === 0) {
+    throw new AppError(
+      ErrorCodes.CACHE_MISS,
+      `No cache entries found for skill '${fullName}'`,
+      404
+    );
+  }
+
+  const totalHits = skillCache.reduce((sum, c) => sum + c.hitCount, 0);
+  const totalSize = skillCache.reduce((sum, c) => sum + (c.size ?? 0), 0);
+
+  sendSuccess(request, reply, {
+    skillName: fullName,
+    versions: skillCache.map(c => ({
+      version: c.version,
+      cachedAt: c.cachedAt,
+      expiresAt: c.expiresAt,
+      size: c.size,
+      hitCount: c.hitCount,
+      lastHitAt: c.lastHitAt,
+      integrityHash: c.integrityHash,
+    })),
+    totalVersions: skillCache.length,
+    totalHits,
+    totalSize,
+  });
+}
+
+/**
+ * Get cache info for a specific version
+ */
+export async function getVersionCacheInfo(
+  request: FastifyRequest<{ Params: SkillVersionParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name, version } = request.params;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const cacheEntry = await storage.getCacheMetadata(fullName, version);
+  if (!cacheEntry) {
+    throw new AppError(
+      ErrorCodes.CACHE_MISS,
+      `No cache entry found for '${fullName}@${version}'`,
+      404
+    );
+  }
+
+  sendSuccess(request, reply, cacheEntry);
+}
+
+/**
+ * Invalidate cache for a skill
+ */
+export async function invalidateSkillCache(
+  request: FastifyRequest<{ Params: SkillNameParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const userId = request.user?.id;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const deleted = await storage.deleteCacheMetadata(fullName);
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp: now(),
+    eventType: 'cache.invalidated',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'skill',
+      name: fullName,
+    },
+    action: 'invalidate_cache',
+    result: deleted ? 'success' : 'failure',
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Cache invalidated', { skillName: fullName, deleted });
+
+  sendSuccess(request, reply, { invalidated: deleted });
+}
+
+/**
+ * Invalidate cache for a specific version
+ */
+export async function invalidateVersionCache(
+  request: FastifyRequest<{ Params: SkillVersionParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name, version } = request.params;
+  const userId = request.user?.id;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const deleted = await storage.deleteCacheMetadata(fullName, version);
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp: now(),
+    eventType: 'cache.invalidated',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'version',
+      name: fullName,
+      version,
+    },
+    action: 'invalidate_cache',
+    result: deleted ? 'success' : 'failure',
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Version cache invalidated', { skillName: fullName, version, deleted });
+
+  sendSuccess(request, reply, { invalidated: deleted });
+}
+
+/**
+ * Clean expired cache entries
+ */
+export async function cleanExpiredCache(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const userId = request.user?.id;
+
+  const expiredEntries = await storage.getExpiredCacheEntries();
+  let cleaned = 0;
+
+  for (const entry of expiredEntries) {
+    const deleted = await storage.deleteCacheMetadata(entry.skillName, entry.version);
+    if (deleted) cleaned++;
+  }
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp: now(),
+    eventType: 'cache.invalidated',
+    actor: {
+      type: request.user?.type ?? 'system',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'config',
+      name: 'cache',
+    },
+    action: 'clean_expired',
+    result: 'success',
+    details: {
+      expired: expiredEntries.length,
+      cleaned,
+    },
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Expired cache cleaned', { expired: expiredEntries.length, cleaned });
+
+  sendSuccess(request, reply, {
+    expired: expiredEntries.length,
+    cleaned,
+  });
+}
+
+/**
+ * Get cache statistics
+ */
+export async function getCacheStats(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const config = getConfig().get();
+
+  const cacheEntries = await storage.getAllCacheMetadata();
+  const expiredEntries = await storage.getExpiredCacheEntries();
+
+  const totalSize = cacheEntries.reduce((sum, c) => sum + (c.size ?? 0), 0);
+  const totalHits = cacheEntries.reduce((sum, c) => sum + c.hitCount, 0);
+  const uniqueSkills = new Set(cacheEntries.map(c => c.skillName)).size;
+
+  // Most accessed
+  const mostAccessed = [...cacheEntries]
+    .sort((a, b) => b.hitCount - a.hitCount)
+    .slice(0, 10)
+    .map(c => ({
+      skillName: c.skillName,
+      version: c.version,
+      hitCount: c.hitCount,
+    }));
+
+  // Recently cached
+  const recentlyCached = [...cacheEntries]
+    .sort((a, b) => b.cachedAt.localeCompare(a.cachedAt))
+    .slice(0, 10)
+    .map(c => ({
+      skillName: c.skillName,
+      version: c.version,
+      cachedAt: c.cachedAt,
+    }));
+
+  sendSuccess(request, reply, {
+    totalEntries: cacheEntries.length,
+    uniqueSkills,
+    totalSize,
+    totalHits,
+    expiredCount: expiredEntries.length,
+    config: {
+      ttl: config.cache.ttl,
+      maxSize: config.cache.maxSize,
+      strategy: config.cache.strategy,
+    },
+    utilization: config.cache.maxSize > 0
+      ? Math.round((totalSize / config.cache.maxSize) * 100)
+      : 0,
+    mostAccessed,
+    recentlyCached,
+  });
+}

package/src/controllers/feedback.ts

@@ -0,0 +1,309 @@
+/**
+ * Open Skills Hub - Feedback Controller
+ */
+
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import {
+  getStorage,
+  generateUUID,
+  now,
+  hashIP,
+  buildSkillFullName,
+  parseSkillFullName,
+  AppError,
+  ErrorCodes,
+} from '@open-skills-hub/core';
+import type { Feedback, AuditLog } from '@open-skills-hub/core';
+import { sendSuccess } from '../middleware/error.js';
+import { logger } from '../middleware/logger.js';
+import type {
+  SkillNameParam,
+  IdParam,
+  SubmitFeedbackBody,
+  PaginationQuery,
+} from '../middleware/validation.js';
+
+/**
+ * Submit feedback for a skill
+ */
+export async function submitFeedback(
+  request: FastifyRequest<{ Body: SubmitFeedbackBody }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const body = request.body;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(body.skillName);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  // Verify version exists
+  const version = await storage.getVersion(skill.id, body.skillVersion);
+  if (!version) {
+    throw new AppError(
+      ErrorCodes.VERSION_NOT_FOUND,
+      `Version '${body.skillVersion}' not found for skill '${fullName}'`,
+      404
+    );
+  }
+
+  const feedbackId = generateUUID();
+  const timestamp = now();
+
+  const feedback: Feedback = {
+    id: feedbackId,
+    skillId: skill.id,
+    skillVersion: body.skillVersion,
+    feedbackType: body.feedbackType,
+    rating: body.rating,
+    comment: body.comment,
+    context: body.context ?? {},
+    status: 'pending',
+    sourceIpHash: hashIP(request.ip),
+    createdAt: timestamp,
+  };
+
+  await storage.createFeedback(feedback);
+
+  // Update skill rating if this is a rating feedback
+  if (body.rating) {
+    const feedbacks = await storage.getFeedbacks(skill.id, { limit: 1000 });
+    const ratings = feedbacks.items.map(f => f.rating).filter((r): r is number => r !== undefined);
+    const averageRating = ratings.length > 0
+      ? ratings.reduce((sum, r) => sum + r, 0) / ratings.length
+      : 0;
+
+    await storage.updateSkill(skill.id, {
+      rating: {
+        average: Math.round(averageRating * 10) / 10,
+        count: ratings.length,
+      },
+    });
+  }
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp,
+    eventType: 'feedback.submitted',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: request.user?.id,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'feedback',
+      id: feedbackId,
+      name: fullName,
+      version: body.skillVersion,
+    },
+    action: 'create',
+    result: 'success',
+    details: {
+      feedbackType: body.feedbackType,
+      rating: body.rating,
+    },
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Feedback submitted', {
+    feedbackId,
+    skillName: fullName,
+    feedbackType: body.feedbackType,
+    rating: body.rating,
+  });
+
+  sendSuccess(request, reply, {
+    id: feedbackId,
+    status: 'pending',
+    createdAt: timestamp,
+  }, 201);
+}
+
+/**
+ * Get feedbacks for a skill
+ */
+export async function getSkillFeedbacks(
+  request: FastifyRequest<{
+    Params: SkillNameParam;
+    Querystring: PaginationQuery & { feedbackType?: string; status?: string }
+  }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const { cursor, limit, feedbackType, status } = request.query;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  const result = await storage.getFeedbacks(skill.id, {
+    cursor,
+    limit,
+    feedbackType,
+    status,
+  });
+
+  // Remove sensitive data
+  const feedbacks = result.items.map(f => ({
+    id: f.id,
+    skillVersion: f.skillVersion,
+    feedbackType: f.feedbackType,
+    rating: f.rating,
+    comment: f.comment,
+    context: f.context,
+    status: f.status,
+    createdAt: f.createdAt,
+  }));
+
+  sendSuccess(request, reply, feedbacks, 200, result.pagination);
+}
+
+/**
+ * Get feedback by ID
+ */
+export async function getFeedbackById(
+  request: FastifyRequest<{ Params: IdParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { id } = request.params;
+
+  const feedback = await storage.getFeedbackById(id);
+  if (!feedback) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND, // Using generic not found
+      `Feedback '${id}' not found`,
+      404
+    );
+  }
+
+  sendSuccess(request, reply, {
+    id: feedback.id,
+    skillId: feedback.skillId,
+    skillVersion: feedback.skillVersion,
+    feedbackType: feedback.feedbackType,
+    rating: feedback.rating,
+    comment: feedback.comment,
+    context: feedback.context,
+    status: feedback.status,
+    createdAt: feedback.createdAt,
+  });
+}
+
+/**
+ * Review feedback (admin)
+ */
+export async function reviewFeedback(
+  request: FastifyRequest<{
+    Params: IdParam;
+    Body: { status: 'reviewed' | 'accepted' | 'rejected'; notes?: string }
+  }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { id } = request.params;
+  const { status, notes } = request.body;
+  const userId = request.user?.id;
+
+  const feedback = await storage.getFeedbackById(id);
+  if (!feedback) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Feedback '${id}' not found`,
+      404
+    );
+  }
+
+  const updated = await storage.updateFeedback(id, {
+    status,
+    reviewerNotes: notes,
+    reviewedAt: now(),
+    reviewedBy: userId,
+  });
+
+  logger.info('Feedback reviewed', {
+    feedbackId: id,
+    status,
+    reviewedBy: userId,
+  });
+
+  sendSuccess(request, reply, {
+    id: updated?.id,
+    status: updated?.status,
+    reviewerNotes: updated?.reviewerNotes,
+    reviewedAt: updated?.reviewedAt,
+  });
+}
+
+/**
+ * Get feedback statistics for a skill
+ */
+export async function getFeedbackStats(
+  request: FastifyRequest<{ Params: SkillNameParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  // Get all feedbacks
+  const result = await storage.getFeedbacks(skill.id, { limit: 1000 });
+  const feedbacks = result.items;
+
+  // Calculate stats
+  const stats = {
+    total: feedbacks.length,
+    byType: {
+      success: feedbacks.filter(f => f.feedbackType === 'success').length,
+      failure: feedbacks.filter(f => f.feedbackType === 'failure').length,
+      suggestion: feedbacks.filter(f => f.feedbackType === 'suggestion').length,
+      bug: feedbacks.filter(f => f.feedbackType === 'bug').length,
+    },
+    byStatus: {
+      pending: feedbacks.filter(f => f.status === 'pending').length,
+      reviewed: feedbacks.filter(f => f.status === 'reviewed').length,
+      accepted: feedbacks.filter(f => f.status === 'accepted').length,
+      rejected: feedbacks.filter(f => f.status === 'rejected').length,
+    },
+    rating: skill.rating,
+    successRate: feedbacks.length > 0
+      ? feedbacks.filter(f => f.feedbackType === 'success').length / feedbacks.length
+      : 0,
+  };
+
+  sendSuccess(request, reply, stats);
+}

package/src/controllers/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Open Skills Hub - Controllers Exports
+ */
+
+export * from './skills.js';
+export * from './versions.js';
+export * from './feedback.js';
+export * from './audit.js';
+export * from './cache.js';