@doccov/api 0.4.0 → 0.5.0

package/src/routes/badge.ts

@@ -1,8 +1,11 @@
+import { fetchSpec } from '@doccov/sdk';
+import { validateSpec } from '@openpkg-ts/spec';
 import { Hono } from 'hono';
-import { fetchSpecFromGitHub } from '../utils/github';
 
 export const badgeRoute = new Hono();
 
+type BadgeStyle = 'flat' | 'flat-square' | 'for-the-badge';
+
 type BadgeColor =
   | 'brightgreen'
   | 'green'
@@ -16,6 +19,7 @@ interface BadgeOptions {
   label: string;
   message: string;
   color: BadgeColor;
+  style?: BadgeStyle;
 }
 
 function getColorForScore(score: number): BadgeColor {
@@ -27,22 +31,17 @@ function getColorForScore(score: number): BadgeColor {
   return 'red';
 }
 
-function generateBadgeSvg(options: BadgeOptions): string {
-  const { label, message, color } = options;
-
-  const colors: Record<BadgeColor, string> = {
-    brightgreen: '#4c1',
-    green: '#97ca00',
-    yellowgreen: '#a4a61d',
-    yellow: '#dfb317',
-    orange: '#fe7d37',
-    red: '#e05d44',
-    lightgrey: '#9f9f9f',
-  };
-
-  const bgColor = colors[color];
-
-  // Simple badge dimensions
+const BADGE_COLORS: Record<BadgeColor, string> = {
+  brightgreen: '#4c1',
+  green: '#97ca00',
+  yellowgreen: '#a4a61d',
+  yellow: '#dfb317',
+  orange: '#fe7d37',
+  red: '#e05d44',
+  lightgrey: '#9f9f9f',
+};
+
+function generateFlatBadge(label: string, message: string, bgColor: string): string {
   const labelWidth = label.length * 7 + 10;
   const messageWidth = message.length * 7 + 10;
   const totalWidth = labelWidth + messageWidth;
@@ -70,49 +69,139 @@ function generateBadgeSvg(options: BadgeOptions): string {
 </svg>`;
 }
 
+function generateFlatSquareBadge(label: string, message: string, bgColor: string): string {
+  const labelWidth = label.length * 7 + 10;
+  const messageWidth = message.length * 7 + 10;
+  const totalWidth = labelWidth + messageWidth;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${label}: ${message}">
+  <title>${label}: ${message}</title>
+  <g shape-rendering="crispEdges">
+    <rect width="${labelWidth}" height="20" fill="#555"/>
+    <rect x="${labelWidth}" width="${messageWidth}" height="20" fill="${bgColor}"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
+    <text x="${labelWidth / 2}" y="14">${label}</text>
+    <text x="${labelWidth + messageWidth / 2}" y="14">${message}</text>
+  </g>
+</svg>`;
+}
+
+function generateForTheBadge(label: string, message: string, bgColor: string): string {
+  const labelUpper = label.toUpperCase();
+  const messageUpper = message.toUpperCase();
+  const labelWidth = labelUpper.length * 10 + 20;
+  const messageWidth = messageUpper.length * 10 + 20;
+  const totalWidth = labelWidth + messageWidth;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="28" role="img" aria-label="${label}: ${message}">
+  <title>${label}: ${message}</title>
+  <g shape-rendering="crispEdges">
+    <rect width="${labelWidth}" height="28" fill="#555"/>
+    <rect x="${labelWidth}" width="${messageWidth}" height="28" fill="${bgColor}"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="10" font-weight="bold">
+    <text x="${labelWidth / 2}" y="18">${labelUpper}</text>
+    <text x="${labelWidth + messageWidth / 2}" y="18">${messageUpper}</text>
+  </g>
+</svg>`;
+}
+
+function generateBadgeSvg(options: BadgeOptions): string {
+  const { label, message, color, style = 'flat' } = options;
+  const bgColor = BADGE_COLORS[color];
+
+  switch (style) {
+    case 'flat-square':
+      return generateFlatSquareBadge(label, message, bgColor);
+    case 'for-the-badge':
+      return generateForTheBadge(label, message, bgColor);
+    default:
+      return generateFlatBadge(label, message, bgColor);
+  }
+}
+
+/**
+ * Compute coverage score from spec exports if not already present.
+ */
+function computeCoverageScore(spec: { exports?: { description?: string }[] }): number {
+  const exports = spec.exports ?? [];
+  if (exports.length === 0) return 0;
+
+  const documented = exports.filter((e) => e.description && e.description.trim().length > 0);
+  return Math.round((documented.length / exports.length) * 100);
+}
+
+// Cache headers: 5min max-age, stale-if-error for resilience
+const CACHE_HEADERS_SUCCESS = {
+  'Content-Type': 'image/svg+xml',
+  'Cache-Control': 'public, max-age=300, stale-if-error=3600',
+};
+
+const CACHE_HEADERS_ERROR = {
+  'Content-Type': 'image/svg+xml',
+  'Cache-Control': 'no-cache',
+};
+
 // GET /badge/:owner/:repo
 badgeRoute.get('/:owner/:repo', async (c) => {
   const { owner, repo } = c.req.param();
-  const branch = c.req.query('branch') ?? 'main';
+
+  // Query params for customization
+  const ref = c.req.query('ref') ?? c.req.query('branch') ?? 'main';
+  const specPath = c.req.query('path') ?? c.req.query('package') ?? 'openpkg.json';
+  const style = (c.req.query('style') ?? 'flat') as BadgeStyle;
 
   try {
-    const spec = await fetchSpecFromGitHub(owner, repo, branch);
+    const spec = await fetchSpec(owner, repo, { ref, path: specPath });
 
     if (!spec) {
       const svg = generateBadgeSvg({
         label: 'docs',
         message: 'not found',
         color: 'lightgrey',
+        style,
       });
 
-      return c.body(svg, 404, {
-        'Content-Type': 'image/svg+xml',
-        'Cache-Control': 'no-cache',
+      return c.body(svg, 404, CACHE_HEADERS_ERROR);
+    }
+
+    // Validate spec against schema
+    const validation = validateSpec(spec);
+    if (!validation.ok) {
+      const svg = generateBadgeSvg({
+        label: 'docs',
+        message: 'invalid',
+        color: 'lightgrey',
+        style,
       });
+
+      return c.body(svg, 422, CACHE_HEADERS_ERROR);
     }
 
-    const coverageScore = spec.docs?.coverageScore ?? 0;
+    // Use docs.coverageScore if present (enriched spec), otherwise compute from exports
+    // Note: The spec type has changed - check for generation.analysis or similar patterns
+    const coverageScore =
+      (spec as { docs?: { coverageScore?: number } }).docs?.coverageScore ??
+      computeCoverageScore(spec);
+
     const svg = generateBadgeSvg({
       label: 'docs',
       message: `${coverageScore}%`,
       color: getColorForScore(coverageScore),
+      style,
     });
 
-    return c.body(svg, 200, {
-      'Content-Type': 'image/svg+xml',
-      'Cache-Control': 'public, max-age=300', // Cache for 5 minutes
-    });
+    return c.body(svg, 200, CACHE_HEADERS_SUCCESS);
   } catch {
     const svg = generateBadgeSvg({
       label: 'docs',
       message: 'error',
       color: 'red',
+      style,
     });
 
-    return c.body(svg, 500, {
-      'Content-Type': 'image/svg+xml',
-      'Cache-Control': 'no-cache',
-    });
+    return c.body(svg, 500, CACHE_HEADERS_ERROR);
   }
 });
 
@@ -120,5 +209,6 @@ badgeRoute.get('/:owner/:repo', async (c) => {
 badgeRoute.get('/:owner/:repo.svg', async (c) => {
   const { owner, repo } = c.req.param();
   const repoName = repo.replace(/\.svg$/, '');
-  return c.redirect(`/badge/${owner}/${repoName}`);
+  const query = new URL(c.req.url).search;
+  return c.redirect(`/badge/${owner}/${repoName}${query}`);
 });

package/src/routes/billing.ts

@@ -1,3 +1,4 @@
+import { getPlanLimits, type Plan } from '@doccov/db';
 import { CustomerPortal, Webhooks } from '@polar-sh/hono';
 import { Hono } from 'hono';
 import { auth } from '../auth/config';
@@ -200,3 +201,67 @@ billingRoute.get('/status', async (c) => {
     portalUrl: org.polarCustomerId ? `${API_URL}/billing/portal?orgId=${orgId}` : null,
   });
 });
+
+// ============ Usage Details ============
+billingRoute.get('/usage', async (c) => {
+  const orgId = c.req.query('orgId');
+  if (!orgId) return c.json({ error: 'orgId required' }, 400);
+
+  const session = await auth.api.getSession({ headers: c.req.raw.headers });
+  if (!session) return c.json({ error: 'Unauthorized' }, 401);
+
+  // Get org with member count
+  const org = await db
+    .selectFrom('organizations')
+    .innerJoin('org_members', 'org_members.orgId', 'organizations.id')
+    .where('organizations.id', '=', orgId)
+    .where('org_members.userId', '=', session.user.id)
+    .select([
+      'organizations.id',
+      'organizations.plan',
+      'organizations.aiCallsUsed',
+      'organizations.aiCallsResetAt',
+    ])
+    .executeTakeFirst();
+
+  if (!org) return c.json({ error: 'Organization not found' }, 404);
+
+  // Get member count
+  const memberResult = await db
+    .selectFrom('org_members')
+    .where('orgId', '=', orgId)
+    .select(db.fn.countAll<number>().as('count'))
+    .executeTakeFirst();
+
+  const seats = memberResult?.count ?? 1;
+  const limits = getPlanLimits(org.plan as Plan);
+
+  // Calculate next reset date
+  const now = new Date();
+  const resetAt = org.aiCallsResetAt || new Date(now.getFullYear(), now.getMonth() + 1, 1);
+  const shouldReset = !org.aiCallsResetAt || now >= org.aiCallsResetAt;
+  const aiUsed = shouldReset ? 0 : org.aiCallsUsed;
+
+  // Calculate pricing based on plan
+  const pricing: Record<string, number> = { free: 0, team: 15, pro: 49 };
+  const monthlyCost = (pricing[org.plan] ?? 0) * seats;
+
+  return c.json({
+    plan: org.plan,
+    seats,
+    monthlyCost,
+    aiCalls: {
+      used: aiUsed,
+      limit: limits.aiCallsPerMonth === Infinity ? 'unlimited' : limits.aiCallsPerMonth,
+      resetAt: resetAt.toISOString(),
+    },
+    analyses: {
+      limit: limits.analysesPerDay === Infinity ? 'unlimited' : limits.analysesPerDay,
+      resetAt: 'daily',
+    },
+    history: {
+      days: limits.historyDays,
+    },
+    privateRepos: limits.privateRepos === Infinity,
+  });
+});

package/src/routes/coverage.ts

@@ -1,3 +1,4 @@
+import { getPlanLimits, type Plan } from '@doccov/db';
 import { Hono } from 'hono';
 import { nanoid } from 'nanoid';
 import { auth } from '../auth/config';
@@ -29,33 +30,50 @@ coverageRoute.get('/projects/:projectId/history', async (c) => {
   const { projectId } = c.req.param();
   const { range = '30d', limit = '50' } = c.req.query();
 
-  // Verify user has access to project
-  const project = await db
+  // Verify user has access to project and get org plan
+  const projectWithOrg = await db
     .selectFrom('projects')
     .innerJoin('org_members', 'org_members.orgId', 'projects.orgId')
+    .innerJoin('organizations', 'organizations.id', 'projects.orgId')
     .where('projects.id', '=', projectId)
     .where('org_members.userId', '=', session.user.id)
-    .select(['projects.id', 'projects.name'])
+    .select(['projects.id', 'projects.name', 'organizations.plan'])
     .executeTakeFirst();
 
-  if (!project) {
+  if (!projectWithOrg) {
     return c.json({ error: 'Project not found' }, 404);
   }
 
-  // Calculate date filter based on range
+  // Check plan limits for trends access
+  const planLimits = getPlanLimits(projectWithOrg.plan as Plan);
+  if (planLimits.historyDays === 0) {
+    return c.json(
+      {
+        error: 'Coverage trends require Team plan or higher',
+        upgrade: 'https://doccov.com/pricing',
+      },
+      403,
+    );
+  }
+
+  // Calculate date filter based on range (capped by plan limit)
   let dateFilter: Date | null = null;
   const now = new Date();
-  switch (range) {
-    case '7d':
-      dateFilter = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
-      break;
-    case '30d':
-      dateFilter = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
-      break;
-    case '90d':
-      dateFilter = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1000);
-      break;
-    // 'all' and 'versions' - no date filter
+  const maxDays = planLimits.historyDays;
+
+  // Map range to days, capped by plan limit
+  const rangeDays: Record<string, number> = {
+    '7d': Math.min(7, maxDays),
+    '30d': Math.min(30, maxDays),
+    '90d': Math.min(90, maxDays),
+  };
+
+  if (range in rangeDays) {
+    const days = rangeDays[range];
+    dateFilter = new Date(now.getTime() - days * 24 * 60 * 60 * 1000);
+  } else if (range === 'all' || range === 'versions') {
+    // Still cap by plan limit
+    dateFilter = new Date(now.getTime() - maxDays * 24 * 60 * 60 * 1000);
   }
 
   let query = db

package/src/routes/demo.ts

@@ -0,0 +1,297 @@
+/**
+ * Demo route - public "Try it Now" endpoint for analyzing npm packages
+ * Uses the /plan and /execute-stream endpoints from the Vercel API
+ */
+
+import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import { anonymousRateLimit } from '../middleware/anonymous-rate-limit';
+
+export const demoRoute = new Hono();
+
+// Vercel API URL (where /plan and /execute-stream live)
+const VERCEL_API_URL = process.env.VERCEL_API_URL || 'https://api-khaki-phi.vercel.app';
+
+// Rate limit: 5 analyses per hour per IP
+demoRoute.use(
+  '*',
+  anonymousRateLimit({
+    windowMs: 60 * 60 * 1000, // 1 hour
+    max: 5,
+    message: 'Demo limit reached. Sign up for unlimited access.',
+    upgradeUrl: 'https://doccov.com/pricing',
+  }),
+);
+
+/**
+ * npm package info from registry
+ */
+interface NpmPackageInfo {
+  name: string;
+  version: string;
+  description?: string;
+  repository?: string;
+}
+
+/**
+ * Fetch package info from npm registry
+ */
+async function fetchNpmPackage(packageName: string): Promise<NpmPackageInfo> {
+  const encodedName = encodeURIComponent(packageName);
+  const url = `https://registry.npmjs.org/${encodedName}/latest`;
+
+  const res = await fetch(url, {
+    headers: { Accept: 'application/json' },
+  });
+
+  if (!res.ok) {
+    if (res.status === 404) {
+      throw new Error(`Package "${packageName}" not found on npm`);
+    }
+    throw new Error(`npm registry error: ${res.status}`);
+  }
+
+  const data = (await res.json()) as {
+    name: string;
+    version: string;
+    description?: string;
+    repository?: string | { type?: string; url?: string };
+  };
+
+  // Extract and normalize GitHub URL from repository field
+  let repoUrl: string | undefined;
+  if (data.repository) {
+    if (typeof data.repository === 'string') {
+      repoUrl = data.repository;
+    } else if (data.repository.url) {
+      // Normalize: git+https://github.com/... or git://github.com/...
+      repoUrl = data.repository.url
+        .replace(/^git\+/, '')
+        .replace(/^git:\/\//, 'https://')
+        .replace(/\.git$/, '');
+    }
+  }
+
+  // Validate it's a GitHub URL
+  if (repoUrl && !repoUrl.includes('github.com')) {
+    repoUrl = undefined;
+  }
+
+  return {
+    name: data.name,
+    version: data.version,
+    description: data.description,
+    repository: repoUrl,
+  };
+}
+
+/**
+ * Analysis result summary (matches SpecSummary from Vercel API)
+ */
+interface AnalysisSummary {
+  packageName: string;
+  version: string;
+  coverage: number;
+  exportCount: number;
+  documentedCount: number;
+  undocumentedCount: number;
+  driftCount: number;
+  topUndocumented: string[];
+  topDrift: Array<{ name: string; issue: string }>;
+}
+
+// GET /demo/analyze?package=lodash
+demoRoute.get('/analyze', async (c) => {
+  const packageName = c.req.query('package');
+
+  if (!packageName) {
+    return c.json({ error: 'Package name required' }, 400);
+  }
+
+  // Validate package name (basic sanitation)
+  if (!/^(@[\w-]+\/)?[\w.-]+$/.test(packageName)) {
+    return c.json({ error: 'Invalid package name format' }, 400);
+  }
+
+  return streamSSE(c, async (stream) => {
+    const sendEvent = async (
+      type: 'status' | 'log' | 'result' | 'error',
+      data: { step?: string; message?: string; data?: unknown },
+    ) => {
+      await stream.writeSSE({
+        data: JSON.stringify({ type, ...data }),
+        event: type === 'error' ? 'error' : type === 'result' ? 'complete' : 'progress',
+      });
+    };
+
+    try {
+      // Step 1: Fetch from npm registry
+      await sendEvent('status', {
+        step: 'npm',
+        message: `Fetching ${packageName} from npm registry...`,
+      });
+
+      const npmInfo = await fetchNpmPackage(packageName);
+
+      await sendEvent('log', {
+        message: `Found ${npmInfo.name}@${npmInfo.version}`,
+      });
+
+      if (!npmInfo.repository) {
+        await sendEvent('error', {
+          message: 'No GitHub repository linked to this package',
+        });
+        return;
+      }
+
+      await sendEvent('log', {
+        message: `Repository: ${npmInfo.repository}`,
+      });
+
+      // Step 2: Generate build plan via /plan endpoint
+      await sendEvent('status', {
+        step: 'plan',
+        message: 'Generating build plan...',
+      });
+
+      const planResponse = await fetch(`${VERCEL_API_URL}/plan`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          url: npmInfo.repository,
+          package: packageName.startsWith('@') ? packageName : undefined,
+        }),
+      });
+
+      if (!planResponse.ok) {
+        const errorData = (await planResponse.json()) as { error?: string };
+        throw new Error(errorData.error || `Plan generation failed: ${planResponse.status}`);
+      }
+
+      const planData = (await planResponse.json()) as {
+        plan: unknown;
+        context: { isMonorepo: boolean; packageManager: string };
+      };
+
+      await sendEvent('log', {
+        message: `Build plan ready (${planData.context.packageManager}${planData.context.isMonorepo ? ', monorepo' : ''})`,
+      });
+
+      // Step 3: Execute build plan via /execute-stream endpoint
+      await sendEvent('status', {
+        step: 'build',
+        message: 'Building and analyzing...',
+      });
+
+      const executeResponse = await fetch(`${VERCEL_API_URL}/execute-stream`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ plan: planData.plan }),
+      });
+
+      if (!executeResponse.ok || !executeResponse.body) {
+        throw new Error(`Execution failed: ${executeResponse.status}`);
+      }
+
+      // Stream the execute-stream SSE events and forward relevant ones
+      const reader = executeResponse.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          if (line.startsWith('event:')) {
+            const eventType = line.slice(7).trim();
+
+            // Get the next data line
+            const dataLineIndex = lines.indexOf(line) + 1;
+            if (dataLineIndex < lines.length && lines[dataLineIndex].startsWith('data:')) {
+              const dataStr = lines[dataLineIndex].slice(5).trim();
+              try {
+                const eventData = JSON.parse(dataStr) as {
+                  stage?: string;
+                  message?: string;
+                  stepId?: string;
+                  name?: string;
+                  success?: boolean;
+                  summary?: {
+                    name: string;
+                    version: string;
+                    coverage: number;
+                    exports: number;
+                    documented: number;
+                    undocumented: number;
+                  };
+                  error?: string;
+                };
+
+                // Forward progress events
+                if (eventType === 'progress') {
+                  await sendEvent('log', { message: eventData.message || eventData.stage });
+                } else if (eventType === 'step:start') {
+                  await sendEvent('status', {
+                    step: eventData.stepId === 'analyze' ? 'analyze' : 'build',
+                    message: eventData.name || `Running ${eventData.stepId}...`,
+                  });
+                } else if (eventType === 'step:complete' && eventData.stepId) {
+                  await sendEvent('log', {
+                    message: `${eventData.stepId} completed`,
+                  });
+                } else if (eventType === 'complete' && eventData.summary) {
+                  // Transform summary to our format
+                  const summary: AnalysisSummary = {
+                    packageName: eventData.summary.name,
+                    version: eventData.summary.version,
+                    coverage: eventData.summary.coverage,
+                    exportCount: eventData.summary.exports,
+                    documentedCount: eventData.summary.documented,
+                    undocumentedCount: eventData.summary.undocumented,
+                    driftCount: 0,
+                    topUndocumented: [],
+                    topDrift: [],
+                  };
+
+                  await sendEvent('log', {
+                    message: `Found ${summary.exportCount} exports, ${summary.documentedCount} documented`,
+                  });
+
+                  await sendEvent('status', {
+                    step: 'complete',
+                    message: 'Analysis complete!',
+                  });
+
+                  await sendEvent('result', { data: summary });
+                  return;
+                } else if (eventType === 'error') {
+                  throw new Error(eventData.error || 'Execution failed');
+                }
+              } catch (parseError) {
+                // Ignore JSON parse errors for incomplete data
+                if (parseError instanceof SyntaxError) continue;
+                throw parseError;
+              }
+            }
+          }
+        }
+      }
+
+      // If we get here without a complete event, something went wrong
+      throw new Error('Execution completed without results');
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Analysis failed';
+      await sendEvent('error', { message });
+    }
+  });
+});
+
+// Health check
+demoRoute.get('/health', (c) => {
+  return c.json({ status: 'ok' });
+});