@doccov/api 0.4.0 → 0.6.0

package/src/routes/ai.ts

@@ -0,0 +1,353 @@
+/**
+ * AI generation endpoint
+ *
+ * POST /v1/ai/generate - Generate JSDoc for undocumented exports
+ */
+
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { getPlanLimits, type Plan } from '@doccov/db';
+import { generateObject } from 'ai';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { db } from '../db/client';
+import type { ApiKeyContext } from '../middleware/api-key-auth';
+
+type AiVariables = {
+  Variables: ApiKeyContext;
+};
+
+const aiRoute = new Hono<AiVariables>();
+
+// Schema for request body
+const GenerateRequestSchema = z.object({
+  exports: z.array(
+    z.object({
+      name: z.string(),
+      kind: z.string(),
+      signature: z.string().optional(),
+      members: z
+        .array(
+          z.object({
+            name: z.string(),
+            type: z.string().optional(),
+          }),
+        )
+        .optional(),
+    }),
+  ),
+  packageName: z.string().optional(),
+});
+
+// Schema for AI-generated JSDoc
+const JSDocGenerationSchema = z.object({
+  description: z.string().describe('1-2 sentence description of what this does'),
+  params: z
+    .array(
+      z.object({
+        name: z.string(),
+        type: z.string().optional(),
+        description: z.string(),
+      }),
+    )
+    .optional()
+    .describe('Parameter descriptions for functions'),
+  returns: z
+    .object({
+      type: z.string().optional(),
+      description: z.string(),
+    })
+    .optional()
+    .describe('Return value description for functions'),
+  example: z.string().optional().describe('Working code example showing typical usage'),
+  typeParams: z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string(),
+      }),
+    )
+    .optional()
+    .describe('Type parameter descriptions for generics'),
+});
+
+type JSDocGenerationResult = z.infer<typeof JSDocGenerationSchema>;
+
+/**
+ * Get AI model - uses server-side API keys
+ */
+function getModel() {
+  if (process.env.ANTHROPIC_API_KEY) {
+    const anthropic = createAnthropic();
+    return anthropic('claude-sonnet-4-20250514');
+  }
+
+  if (process.env.OPENAI_API_KEY) {
+    const openai = createOpenAI();
+    return openai('gpt-4o-mini');
+  }
+
+  throw new Error('No AI provider configured');
+}
+
+/**
+ * Check and update AI quota for an organization
+ * Returns remaining quota or error
+ */
+async function checkAndUpdateQuota(
+  orgId: string,
+  plan: string,
+  currentUsed: number,
+  resetAt: Date | null,
+  callCount: number,
+): Promise<{ allowed: boolean; remaining: number; resetAt: Date; error?: string }> {
+  const limits = getPlanLimits(plan as Plan);
+  const monthlyLimit = limits.aiCallsPerMonth;
+
+  // Check if unlimited
+  if (monthlyLimit === Infinity) {
+    return { allowed: true, remaining: Infinity, resetAt: new Date() };
+  }
+
+  // Check if we need to reset the counter (monthly)
+  const now = new Date();
+  const shouldReset = !resetAt || now >= resetAt;
+
+  let used = currentUsed;
+  let nextReset = resetAt || getNextMonthReset();
+
+  if (shouldReset) {
+    // Reset the counter
+    used = 0;
+    nextReset = getNextMonthReset();
+
+    await db
+      .updateTable('organizations')
+      .set({
+        aiCallsUsed: 0,
+        aiCallsResetAt: nextReset,
+      })
+      .where('id', '=', orgId)
+      .execute();
+  }
+
+  // Check if over limit
+  if (used + callCount > monthlyLimit) {
+    return {
+      allowed: false,
+      remaining: Math.max(0, monthlyLimit - used),
+      resetAt: nextReset,
+      error: `Monthly AI limit reached (${used}/${monthlyLimit} calls used). Set OPENAI_API_KEY or ANTHROPIC_API_KEY for unlimited.`,
+    };
+  }
+
+  // Increment usage
+  await db
+    .updateTable('organizations')
+    .set({
+      aiCallsUsed: used + callCount,
+    })
+    .where('id', '=', orgId)
+    .execute();
+
+  // Track in usage_records (async)
+  db.insertInto('usage_records')
+    .values({
+      id: crypto.randomUUID(),
+      orgId,
+      feature: 'ai_generate',
+      count: callCount,
+    })
+    .execute()
+    .catch(console.error);
+
+  return {
+    allowed: true,
+    remaining: monthlyLimit - (used + callCount),
+    resetAt: nextReset,
+  };
+}
+
+/**
+ * Get the first day of next month
+ */
+function getNextMonthReset(): Date {
+  const now = new Date();
+  return new Date(now.getFullYear(), now.getMonth() + 1, 1);
+}
+
+/**
+ * Generate JSDoc for a single export
+ */
+async function generateJSDocForExport(
+  exp: {
+    name: string;
+    kind: string;
+    signature?: string;
+    members?: { name: string; type?: string }[];
+  },
+  packageName?: string,
+): Promise<JSDocGenerationResult> {
+  const membersContext =
+    exp.members && exp.members.length > 0
+      ? `\n\nMembers:\n${exp.members
+          .slice(0, 10)
+          .map((m) => `  - ${m.name}${m.type ? `: ${m.type}` : ''}`)
+          .join('\n')}`
+      : '';
+
+  const prompt = `Generate JSDoc documentation for this TypeScript export.
+
+Name: ${exp.name}
+Kind: ${exp.kind}
+${exp.signature ? `Signature: ${exp.signature}` : ''}${membersContext}
+${packageName ? `Package: ${packageName}` : ''}
+
+Requirements:
+- Description: 1-2 sentences explaining what this does and when to use it
+- For functions: describe each parameter and return value
+- Example: provide a working code snippet showing typical usage
+- Be concise but informative`;
+
+  // biome-ignore lint/suspicious/noExplicitAny: AI SDK type mismatch between LanguageModelV1/V2
+  const { object } = await generateObject({
+    model: getModel() as any,
+    schema: JSDocGenerationSchema,
+    prompt,
+  });
+
+  return object;
+}
+
+// POST /v1/ai/generate
+aiRoute.post('/generate', async (c) => {
+  const org = c.get('org') as {
+    id: string;
+    plan: string;
+    aiCallsUsed: number;
+    aiCallsResetAt: Date | null;
+  };
+
+  if (!org) {
+    return c.json({ error: 'Unauthorized' }, 401);
+  }
+
+  // Parse request body
+  let body: z.infer<typeof GenerateRequestSchema>;
+  try {
+    const raw = await c.req.json();
+    body = GenerateRequestSchema.parse(raw);
+  } catch {
+    return c.json({ error: 'Invalid request body' }, 400);
+  }
+
+  if (body.exports.length === 0) {
+    return c.json({ error: 'No exports provided' }, 400);
+  }
+
+  // Limit batch size
+  if (body.exports.length > 20) {
+    return c.json({ error: 'Maximum 20 exports per request' }, 400);
+  }
+
+  // Check quota before processing
+  const quotaCheck = await checkAndUpdateQuota(
+    org.id,
+    org.plan,
+    org.aiCallsUsed,
+    org.aiCallsResetAt,
+    body.exports.length,
+  );
+
+  if (!quotaCheck.allowed) {
+    return c.json(
+      {
+        error: quotaCheck.error,
+        remaining: quotaCheck.remaining,
+        resetAt: quotaCheck.resetAt.toISOString(),
+        byok: 'Set OPENAI_API_KEY or ANTHROPIC_API_KEY for unlimited generation',
+      },
+      429,
+    );
+  }
+
+  // Generate JSDoc for each export
+  const results: Array<{
+    name: string;
+    patch: JSDocGenerationResult | null;
+    error?: string;
+  }> = [];
+
+  // Process in batches of 3 to avoid rate limits
+  for (let i = 0; i < body.exports.length; i += 3) {
+    const batch = body.exports.slice(i, i + 3);
+    const promises = batch.map(async (exp) => {
+      try {
+        const patch = await generateJSDocForExport(exp, body.packageName);
+        return { name: exp.name, patch };
+      } catch (err) {
+        return {
+          name: exp.name,
+          patch: null,
+          error: err instanceof Error ? err.message : 'Generation failed',
+        };
+      }
+    });
+
+    const batchResults = await Promise.all(promises);
+    results.push(...batchResults);
+  }
+
+  const successful = results.filter((r) => r.patch !== null).length;
+  const failed = results.filter((r) => r.patch === null).length;
+
+  return c.json({
+    success: true,
+    generated: successful,
+    failed,
+    results,
+    quota: {
+      remaining: quotaCheck.remaining,
+      resetAt: quotaCheck.resetAt.toISOString(),
+    },
+  });
+});
+
+// GET /v1/ai/quota - Check remaining AI quota
+aiRoute.get('/quota', async (c) => {
+  const org = c.get('org') as {
+    id: string;
+    plan: string;
+    aiCallsUsed: number;
+    aiCallsResetAt: Date | null;
+  };
+
+  if (!org) {
+    return c.json({ error: 'Unauthorized' }, 401);
+  }
+
+  const limits = getPlanLimits(org.plan as Plan);
+  const monthlyLimit = limits.aiCallsPerMonth;
+
+  // Check if reset is needed
+  const now = new Date();
+  const shouldReset = !org.aiCallsResetAt || now >= org.aiCallsResetAt;
+
+  let used = org.aiCallsUsed;
+  let resetAt = org.aiCallsResetAt || getNextMonthReset();
+
+  if (shouldReset) {
+    used = 0;
+    resetAt = getNextMonthReset();
+  }
+
+  return c.json({
+    plan: org.plan,
+    used,
+    limit: monthlyLimit === Infinity ? 'unlimited' : monthlyLimit,
+    remaining: monthlyLimit === Infinity ? 'unlimited' : Math.max(0, monthlyLimit - used),
+    resetAt: resetAt.toISOString(),
+  });
+});
+
+export { aiRoute };

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,
+  });
+});