@commonpub/layer 0.16.2 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -30,7 +30,7 @@
     "@aws-sdk/client-s3": "^3.1010.0",
     "@commonpub/explainer": "^0.7.12",
     "@commonpub/schema": "^0.14.1",
-    "@commonpub/server": "^2.44.2",
+    "@commonpub/server": "^2.45.1",
     "@tiptap/core": "^2.11.0",
     "@tiptap/extension-bold": "^2.11.0",
     "@tiptap/extension-bullet-list": "^2.11.0",
@@ -53,12 +53,12 @@
     "vue": "^3.4.0",
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
-    "@commonpub/config": "0.11.0",
-    "@commonpub/docs": "0.6.2",
-    "@commonpub/auth": "0.5.1",
     "@commonpub/editor": "0.7.9",
     "@commonpub/learning": "0.5.0",
+    "@commonpub/auth": "0.5.1",
     "@commonpub/protocol": "0.9.9",
+    "@commonpub/docs": "0.6.2",
+    "@commonpub/config": "0.11.0",
     "@commonpub/ui": "0.8.5"
   },
   "devDependencies": {

package/pages/admin/api-keys.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { AdminApiKeyView } from '@commonpub/server';
+import type { AdminApiKeyView, ApiKeyUsageStats } from '@commonpub/server';
 import { PUBLIC_API_SCOPES } from '@commonpub/schema';
 
 definePageMeta({ layout: 'admin', middleware: 'auth' });
@@ -119,6 +119,28 @@ function fmtDate(iso: string | null): string {
   if (!iso) return '—';
   return new Date(iso).toLocaleString();
 }
+
+// Usage panel per key — lazy-loaded when the admin expands a row.
+const usageOpen = ref<Record<string, boolean>>({});
+const usageCache = ref<Record<string, ApiKeyUsageStats | 'loading' | 'error'>>({});
+
+async function toggleUsage(keyId: string): Promise<void> {
+  usageOpen.value[keyId] = !usageOpen.value[keyId];
+  if (usageOpen.value[keyId] && !usageCache.value[keyId]) {
+    usageCache.value[keyId] = 'loading';
+    try {
+      const stats = await $fetch<ApiKeyUsageStats>(`/api/admin/api-keys/${keyId}/usage`);
+      usageCache.value[keyId] = stats;
+    } catch {
+      usageCache.value[keyId] = 'error';
+    }
+  }
+}
+
+function fmtErrorRate(rate: number): string {
+  if (rate === 0) return '0%';
+  return `${(rate * 100).toFixed(1)}%`;
+}
 </script>
 
 <template>
@@ -237,7 +259,8 @@ function fmtDate(iso: string | null): string {
         </tr>
       </thead>
       <tbody>
-        <tr v-for="k in data.items" :key="k.id" :class="{ 'cpub-key-revoked': !!k.revokedAt }">
+        <template v-for="k in data.items" :key="k.id">
+        <tr :class="{ 'cpub-key-revoked': !!k.revokedAt }">
           <td>
             <strong>{{ k.name }}</strong>
             <div v-if="k.description" class="cpub-key-desc">{{ k.description }}</div>
@@ -254,16 +277,66 @@ function fmtDate(iso: string | null): string {
             <span v-else class="cpub-key-badge cpub-key-badge-green">Active</span>
           </td>
           <td>
-            <button
-              v-if="!k.revokedAt"
-              class="cpub-btn-link cpub-btn-danger"
-              @click="revoke(k.id, k.name)"
-              :aria-label="`Revoke ${k.name}`"
-            >
-              Revoke
-            </button>
+            <div class="cpub-key-actions">
+              <button
+                class="cpub-btn-link"
+                :aria-expanded="!!usageOpen[k.id]"
+                :aria-label="`Toggle usage for ${k.name}`"
+                @click="toggleUsage(k.id)"
+              >
+                {{ usageOpen[k.id] ? 'Hide usage' : 'Usage' }}
+              </button>
+              <button
+                v-if="!k.revokedAt"
+                class="cpub-btn-link cpub-btn-danger"
+                @click="revoke(k.id, k.name)"
+                :aria-label="`Revoke ${k.name}`"
+              >
+                Revoke
+              </button>
+            </div>
+          </td>
+        </tr>
+        <tr v-if="usageOpen[k.id]" class="cpub-key-usage-row">
+          <td colspan="7">
+            <div v-if="usageCache[k.id] === 'loading'" class="cpub-loading">Loading usage...</div>
+            <p v-else-if="usageCache[k.id] === 'error'" class="cpub-form-error">Failed to load usage.</p>
+            <div v-else-if="usageCache[k.id] && typeof usageCache[k.id] === 'object'" class="cpub-usage-grid">
+              <div class="cpub-usage-stat">
+                <span class="cpub-usage-stat-label">Requests (last {{ (usageCache[k.id] as ApiKeyUsageStats).windowDays }}d)</span>
+                <strong>{{ (usageCache[k.id] as ApiKeyUsageStats).totalRequests.toLocaleString() }}</strong>
+              </div>
+              <div class="cpub-usage-stat">
+                <span class="cpub-usage-stat-label">Errors</span>
+                <strong>{{ (usageCache[k.id] as ApiKeyUsageStats).errorCount }} ({{ fmtErrorRate((usageCache[k.id] as ApiKeyUsageStats).errorRate) }})</strong>
+              </div>
+              <div class="cpub-usage-by-day">
+                <span class="cpub-usage-stat-label">By day</span>
+                <ul>
+                  <li v-for="r in (usageCache[k.id] as ApiKeyUsageStats).requestsByDay" :key="r.day">
+                    <code>{{ r.day }}</code> {{ r.count }}
+                  </li>
+                </ul>
+              </div>
+              <div class="cpub-usage-top">
+                <span class="cpub-usage-stat-label">Top endpoints</span>
+                <table class="cpub-usage-table">
+                  <thead>
+                    <tr><th scope="col">Endpoint</th><th scope="col">Count</th><th scope="col">p95 ms</th></tr>
+                  </thead>
+                  <tbody>
+                    <tr v-for="e in (usageCache[k.id] as ApiKeyUsageStats).topEndpoints" :key="e.endpoint">
+                      <td><code>{{ e.endpoint }}</code></td>
+                      <td>{{ e.count }}</td>
+                      <td>{{ e.p95LatencyMs ?? '—' }}</td>
+                    </tr>
+                  </tbody>
+                </table>
+              </div>
+            </div>
           </td>
         </tr>
+        </template>
       </tbody>
     </table>
   </div>
@@ -356,6 +429,19 @@ function fmtDate(iso: string | null): string {
 .cpub-key-badge-yellow { background: var(--yellow-bg); color: var(--yellow); border: var(--border-width-default) solid var(--yellow); }
 .cpub-key-badge-red { background: var(--red-bg); color: var(--red); border: var(--border-width-default) solid var(--red); }
 
+.cpub-key-actions { display: flex; gap: 8px; }
+.cpub-key-usage-row td { background: var(--surface2); padding: 16px; }
+.cpub-usage-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; }
+.cpub-usage-stat { display: flex; flex-direction: column; gap: 4px; }
+.cpub-usage-stat strong { font-size: 18px; color: var(--text); font-family: var(--font-mono); }
+.cpub-usage-stat-label { font-family: var(--font-mono); font-size: 10px; text-transform: uppercase; letter-spacing: 0.08em; color: var(--text-faint); }
+.cpub-usage-by-day ul { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 2px; font-size: 11px; color: var(--text-dim); }
+.cpub-usage-by-day code { font-family: var(--font-mono); color: var(--text); }
+.cpub-usage-top { grid-column: 1 / -1; }
+.cpub-usage-table { width: 100%; border-collapse: collapse; margin-top: 6px; }
+.cpub-usage-table th, .cpub-usage-table td { padding: 4px 8px; text-align: left; font-size: 11px; border-bottom: var(--border-width-default) solid var(--border2); }
+.cpub-usage-table code { font-family: var(--font-mono); font-size: 10px; }
+
 .cpub-loading { padding: 40px; text-align: center; color: var(--text-dim); }
 .cpub-empty { padding: 40px; text-align: center; color: var(--text-dim); background: var(--surface); border: var(--border-width-default) solid var(--border); }
 .cpub-empty code { font-family: var(--font-mono); background: var(--surface2); padding: 1px 6px; }

package/server/api/admin/api-keys/[id]/usage.get.ts

@@ -0,0 +1,20 @@
+import { getApiKeyById, getApiKeyUsageStats } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  windowDays: z.coerce.number().int().min(1).max(90).default(7),
+});
+
+export default defineEventHandler(async (event) => {
+  requireAdmin(event);
+  const id = getRouterParam(event, 'id');
+  if (!id) throw createError({ statusCode: 400, statusMessage: 'Missing id' });
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters' });
+  }
+  const db = useDB();
+  const key = await getApiKeyById(db, id);
+  if (!key) throw createError({ statusCode: 404, statusMessage: 'Key not found' });
+  return getApiKeyUsageStats(db, id, parsed.data.windowDays);
+});

package/server/api/public/v1/contests/[slug].get.ts

@@ -0,0 +1,15 @@
+import { getContestBySlug, toPublicContest, isPublicContest, type PublicContestRow } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:contests');
+  requireFeature('contests');
+  const slug = getRouterParam(event, 'slug');
+  if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
+  const db = useDB();
+  const config = useConfig();
+  const row = await getContestBySlug(db, slug);
+  if (!row) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  const casted = row as unknown as PublicContestRow;
+  if (!isPublicContest(casted)) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  return toPublicContest(casted, config.instance.domain);
+});

package/server/api/public/v1/contests/index.get.ts

@@ -0,0 +1,26 @@
+import { listContests, toPublicContest, isPublicContest, type PublicContestRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  status: z.enum(['upcoming', 'active', 'judging', 'completed']).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:contests');
+  requireFeature('contests');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const filters = parsed.data;
+  const db = useDB();
+  const config = useConfig();
+  const result = await listContests(db, filters);
+  const domain = config.instance.domain;
+  const items = (result.items as unknown as PublicContestRow[])
+    .filter(isPublicContest)
+    .map((r) => toPublicContest(r, domain));
+  return { items, total: result.total, limit: filters.limit, offset: filters.offset };
+});

package/server/api/public/v1/docs/[slug].get.ts

@@ -0,0 +1,15 @@
+import { getDocsSiteBySlug, toPublicDocSite, isPublicDocSite, type PublicDocSiteRow } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:docs');
+  requireFeature('docs');
+  const slug = getRouterParam(event, 'slug');
+  if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
+  const db = useDB();
+  const config = useConfig();
+  const row = await getDocsSiteBySlug(db, slug);
+  if (!row) throw createError({ statusCode: 404, statusMessage: 'Docs site not found' });
+  const casted = row as unknown as PublicDocSiteRow;
+  if (!isPublicDocSite(casted)) throw createError({ statusCode: 404, statusMessage: 'Docs site not found' });
+  return toPublicDocSite(casted, config.instance.domain);
+});

package/server/api/public/v1/docs/index.get.ts

@@ -0,0 +1,25 @@
+import { listDocsSites, toPublicDocSite, isPublicDocSite, type PublicDocSiteRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:docs');
+  requireFeature('docs');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const { limit, offset } = parsed.data;
+  const db = useDB();
+  const config = useConfig();
+  const result = await listDocsSites(db, { limit, offset });
+  const domain = config.instance.domain;
+  const items = (result.items as unknown as PublicDocSiteRow[])
+    .filter(isPublicDocSite)
+    .map((r) => toPublicDocSite(r, domain));
+  return { items, total: result.total, limit, offset };
+});

package/server/api/public/v1/events/[slug].get.ts

@@ -0,0 +1,15 @@
+import { getEventBySlug, toPublicEvent, isPublicEvent, type PublicEventRow } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:events');
+  requireFeature('events');
+  const slug = getRouterParam(event, 'slug');
+  if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
+  const db = useDB();
+  const config = useConfig();
+  const row = await getEventBySlug(db, slug);
+  if (!row) throw createError({ statusCode: 404, statusMessage: 'Event not found' });
+  const casted = row as unknown as PublicEventRow;
+  if (!isPublicEvent(casted)) throw createError({ statusCode: 404, statusMessage: 'Event not found' });
+  return toPublicEvent(casted, config.instance.domain);
+});

package/server/api/public/v1/events/index.get.ts

@@ -0,0 +1,43 @@
+import { listEvents, toPublicEvent, type PublicEventRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const PUBLIC_STATUSES = new Set(['published', 'active', 'completed']);
+
+const querySchema = z.object({
+  status: z.string().optional(),
+  hubId: z.string().uuid().optional(),
+  upcoming: z.coerce.boolean().optional(),
+  featured: z.coerce.boolean().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:events');
+  requireFeature('events');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const filters = parsed.data;
+  // Non-owner may only request public-safe statuses — anything else coerces to undefined
+  // (list function default), matching the /api/events hardening from session 125.
+  const status = filters.status && PUBLIC_STATUSES.has(filters.status) ? filters.status : undefined;
+  const db = useDB();
+  const config = useConfig();
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result = await listEvents(db, {
+    status: status as any,
+    hubId: filters.hubId,
+    upcoming: filters.upcoming,
+    featured: filters.featured,
+    limit: filters.limit,
+    offset: filters.offset,
+  });
+  const domain = config.instance.domain;
+  const items = (result.items as unknown as PublicEventRow[])
+    .filter((r) => !r.deletedAt && PUBLIC_STATUSES.has(r.status))
+    .map((r) => toPublicEvent(r, domain));
+  return { items, total: result.total, limit: filters.limit, offset: filters.offset };
+});

package/server/api/public/v1/learn/[slug].get.ts

@@ -0,0 +1,15 @@
+import { getPathBySlug, toPublicLearningPath, type PublicLearningPathRow } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:learn');
+  requireFeature('learning');
+  const slug = getRouterParam(event, 'slug');
+  if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
+  const db = useDB();
+  const config = useConfig();
+  const path = await getPathBySlug(db, slug);
+  if (!path || path.status !== 'published' || (path as { deletedAt?: Date | null }).deletedAt) {
+    throw createError({ statusCode: 404, statusMessage: 'Learning path not found' });
+  }
+  return toPublicLearningPath(path as unknown as PublicLearningPathRow, config.instance.domain);
+});

package/server/api/public/v1/learn/index.get.ts

@@ -0,0 +1,31 @@
+import { listPaths, toPublicLearningPath, type PublicLearningPathRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  authorId: z.string().uuid().optional(),
+  difficulty: z.enum(['beginner', 'intermediate', 'advanced']).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:learn');
+  requireFeature('learning');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const filters = parsed.data;
+  const db = useDB();
+  const config = useConfig();
+  const result = await listPaths(db, {
+    status: 'published',
+    authorId: filters.authorId,
+    difficulty: filters.difficulty,
+    limit: filters.limit,
+    offset: filters.offset,
+  });
+  const domain = config.instance.domain;
+  const items = (result.items as unknown as PublicLearningPathRow[]).map((r) => toPublicLearningPath(r, domain));
+  return { items, total: result.total, limit: filters.limit, offset: filters.offset };
+});

package/server/api/public/v1/openapi.json.get.ts

@@ -0,0 +1,372 @@
+import { PUBLIC_API_SCOPES } from '@commonpub/schema';
+
+/**
+ * GET /api/public/v1/openapi.json
+ *
+ * Hand-written OpenAPI 3.1 spec. Requires a valid key with any scope — we
+ * don't expose the spec anonymously because the existence of the API surface
+ * is itself gated by the publicApi feature flag. Consumers typically fetch
+ * the spec once at integration time and paste into Postman/Insomnia; a
+ * per-key spec lets us later vary the spec's advertised scopes by key (not
+ * doing that yet, but leaves the door open).
+ */
+export default defineEventHandler((event) => {
+  // Any valid scope grants access to the spec itself.
+  const scopes = event.context.apiScopes;
+  if (!scopes || scopes.length === 0) {
+    throw createError({ statusCode: 401, statusMessage: 'Missing API key' });
+  }
+
+  const config = useConfig();
+  const base = `https://${config.instance.domain}/api/public/v1`;
+
+  const errorResponse = {
+    type: 'object',
+    properties: {
+      error: { type: 'boolean' },
+      statusCode: { type: 'integer' },
+      statusMessage: { type: 'string' },
+      message: { type: 'string' },
+    },
+  };
+
+  const paginated = (itemsRef: string) => ({
+    type: 'object',
+    required: ['items', 'total', 'limit', 'offset'],
+    properties: {
+      items: { type: 'array', items: { $ref: itemsRef } },
+      total: { type: 'integer' },
+      limit: { type: 'integer' },
+      offset: { type: 'integer' },
+    },
+  });
+
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: `${config.instance.name} Public API`,
+      version: '1.0.0',
+      description:
+        'CommonPub Public Read API. Admin-provisioned Bearer tokens, per-key scopes, read-only in v1. ' +
+        'See https://commonpub.io/docs/public-api for the full reference.',
+      license: { name: 'AGPL-3.0-or-later', url: 'https://www.gnu.org/licenses/agpl-3.0.html' },
+    },
+    servers: [{ url: base }],
+    components: {
+      securitySchemes: {
+        bearer: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'cpub_<env>_<type>_<random>',
+          description: 'Admin-provisioned opaque token. Create keys at /admin/api-keys.',
+        },
+      },
+      schemas: {
+        Error: errorResponse,
+        PublicUser: {
+          type: 'object',
+          required: ['id', 'username', 'createdAt'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            username: { type: 'string' },
+            displayName: { type: 'string', nullable: true },
+            headline: { type: 'string', nullable: true },
+            bio: { type: 'string', nullable: true },
+            avatarUrl: { type: 'string', format: 'uri', nullable: true },
+            bannerUrl: { type: 'string', format: 'uri', nullable: true },
+            pronouns: { type: 'string', nullable: true },
+            location: { type: 'string', nullable: true },
+            website: { type: 'string', format: 'uri', nullable: true },
+            skills: { type: 'array', items: { type: 'string' }, nullable: true },
+            socialLinks: { type: 'object', additionalProperties: { type: 'string' }, nullable: true },
+            createdAt: { type: 'string', format: 'date-time' },
+          },
+        },
+        UserRef: {
+          type: 'object',
+          required: ['id', 'username'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            username: { type: 'string' },
+            displayName: { type: 'string', nullable: true },
+            avatarUrl: { type: 'string', format: 'uri', nullable: true },
+          },
+        },
+        PublicContentSummary: {
+          type: 'object',
+          required: ['id', 'type', 'title', 'slug', 'canonicalUrl', 'source'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            type: { type: 'string', enum: ['project', 'blog', 'explainer'] },
+            title: { type: 'string' },
+            slug: { type: 'string' },
+            description: { type: 'string', nullable: true },
+            coverImageUrl: { type: 'string', format: 'uri', nullable: true },
+            difficulty: { type: 'string', nullable: true },
+            publishedAt: { type: 'string', format: 'date-time', nullable: true },
+            updatedAt: { type: 'string', format: 'date-time' },
+            viewCount: { type: 'integer' },
+            likeCount: { type: 'integer' },
+            commentCount: { type: 'integer' },
+            author: { $ref: '#/components/schemas/UserRef' },
+            canonicalUrl: { type: 'string', format: 'uri' },
+            source: { type: 'string', enum: ['local', 'federated'] },
+            sourceDomain: { type: 'string', nullable: true },
+            sourceUri: { type: 'string', format: 'uri', nullable: true },
+          },
+        },
+        PublicHub: {
+          type: 'object',
+          required: ['id', 'name', 'slug', 'hubType', 'canonicalUrl'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            name: { type: 'string' },
+            slug: { type: 'string' },
+            description: { type: 'string', nullable: true },
+            hubType: { type: 'string', enum: ['community', 'product', 'company'] },
+            iconUrl: { type: 'string', format: 'uri', nullable: true },
+            bannerUrl: { type: 'string', format: 'uri', nullable: true },
+            memberCount: { type: 'integer' },
+            postCount: { type: 'integer' },
+            isOfficial: { type: 'boolean' },
+            categories: { type: 'array', items: { type: 'string' }, nullable: true },
+            website: { type: 'string', format: 'uri', nullable: true },
+            createdAt: { type: 'string', format: 'date-time' },
+            canonicalUrl: { type: 'string', format: 'uri' },
+          },
+        },
+        PublicLearningPath: {
+          type: 'object',
+          required: ['id', 'title', 'slug', 'canonicalUrl'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            title: { type: 'string' },
+            slug: { type: 'string' },
+            description: { type: 'string', nullable: true },
+            coverImageUrl: { type: 'string', format: 'uri', nullable: true },
+            difficulty: { type: 'string', nullable: true },
+            lessonCount: { type: 'integer' },
+            enrollmentCount: { type: 'integer' },
+            publishedAt: { type: 'string', format: 'date-time', nullable: true },
+            createdAt: { type: 'string', format: 'date-time' },
+            author: { $ref: '#/components/schemas/UserRef' },
+            canonicalUrl: { type: 'string', format: 'uri' },
+          },
+        },
+        PublicEvent: {
+          type: 'object',
+          required: ['id', 'title', 'slug', 'startAt', 'canonicalUrl'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            title: { type: 'string' },
+            slug: { type: 'string' },
+            description: { type: 'string', nullable: true },
+            coverImageUrl: { type: 'string', format: 'uri', nullable: true },
+            eventType: { type: 'string' },
+            status: { type: 'string', enum: ['published', 'active', 'completed', 'upcoming', 'past'] },
+            location: { type: 'string', nullable: true },
+            locationUrl: { type: 'string', format: 'uri', nullable: true },
+            startAt: { type: 'string', format: 'date-time' },
+            endAt: { type: 'string', format: 'date-time', nullable: true },
+            timezone: { type: 'string', nullable: true },
+            capacity: { type: 'integer', nullable: true },
+            attendeeCount: { type: 'integer' },
+            waitlistCount: { type: 'integer' },
+            hubId: { type: 'string', format: 'uuid', nullable: true },
+            createdAt: { type: 'string', format: 'date-time' },
+            host: { $ref: '#/components/schemas/UserRef' },
+            canonicalUrl: { type: 'string', format: 'uri' },
+          },
+        },
+        PublicContest: {
+          type: 'object',
+          required: ['id', 'title', 'slug', 'status', 'canonicalUrl'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            title: { type: 'string' },
+            slug: { type: 'string' },
+            description: { type: 'string', nullable: true },
+            bannerUrl: { type: 'string', format: 'uri', nullable: true },
+            status: { type: 'string', enum: ['upcoming', 'active', 'judging', 'completed'] },
+            startDate: { type: 'string', format: 'date-time' },
+            endDate: { type: 'string', format: 'date-time' },
+            entryDeadline: { type: 'string', format: 'date-time', nullable: true },
+            judgingDeadline: { type: 'string', format: 'date-time', nullable: true },
+            prizeDescription: { type: 'string', nullable: true },
+            entryCount: { type: 'integer' },
+            communityVotingEnabled: { type: 'boolean' },
+            createdAt: { type: 'string', format: 'date-time' },
+            canonicalUrl: { type: 'string', format: 'uri' },
+          },
+        },
+        PublicVideo: {
+          type: 'object',
+          required: ['id', 'title', 'url', 'canonicalUrl'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            title: { type: 'string' },
+            description: { type: 'string', nullable: true },
+            url: { type: 'string', format: 'uri' },
+            embedUrl: { type: 'string', format: 'uri', nullable: true },
+            thumbnailUrl: { type: 'string', format: 'uri', nullable: true },
+            duration: { type: 'integer', nullable: true },
+            category: { type: 'object', nullable: true },
+            viewCount: { type: 'integer' },
+            likeCount: { type: 'integer' },
+            createdAt: { type: 'string', format: 'date-time' },
+            author: { $ref: '#/components/schemas/UserRef' },
+            canonicalUrl: { type: 'string', format: 'uri' },
+          },
+        },
+        PublicDocSite: {
+          type: 'object',
+          required: ['id', 'name', 'slug', 'canonicalUrl'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            name: { type: 'string' },
+            slug: { type: 'string' },
+            description: { type: 'string', nullable: true },
+            pageCount: { type: 'integer' },
+            versionCount: { type: 'integer' },
+            defaultVersion: { type: 'string', nullable: true },
+            createdAt: { type: 'string', format: 'date-time' },
+            owner: { $ref: '#/components/schemas/UserRef' },
+            canonicalUrl: { type: 'string', format: 'uri' },
+          },
+        },
+        PublicTag: {
+          type: 'object',
+          required: ['id', 'name', 'slug'],
+          properties: {
+            id: { type: 'string', format: 'uuid' },
+            name: { type: 'string' },
+            slug: { type: 'string' },
+            usageCount: { type: 'integer' },
+            canonicalUrl: { type: 'string', format: 'uri' },
+          },
+        },
+        PublicInstance: {
+          type: 'object',
+          required: ['name', 'domain', 'software'],
+          properties: {
+            name: { type: 'string' },
+            description: { type: 'string', nullable: true },
+            domain: { type: 'string' },
+            software: { type: 'object' },
+            users: { type: 'object' },
+            content: { type: 'object' },
+            hubs: { type: 'object' },
+            features: { type: 'object' },
+            openRegistrations: { type: 'boolean' },
+            links: { type: 'object' },
+          },
+        },
+      },
+    },
+    security: [{ bearer: PUBLIC_API_SCOPES.slice() }],
+    paths: {
+      '/content': {
+        get: {
+          summary: 'List published content',
+          security: [{ bearer: ['read:content'] }],
+          parameters: [
+            { name: 'type', in: 'query', schema: { type: 'string', enum: ['project', 'blog', 'explainer'] } },
+            { name: 'tag', in: 'query', schema: { type: 'string' } },
+            { name: 'authorId', in: 'query', schema: { type: 'string', format: 'uuid' } },
+            { name: 'categoryId', in: 'query', schema: { type: 'string', format: 'uuid' } },
+            { name: 'difficulty', in: 'query', schema: { type: 'string', enum: ['beginner', 'intermediate', 'advanced'] } },
+            { name: 'sort', in: 'query', schema: { type: 'string', enum: ['recent', 'popular', 'featured'] } },
+            { name: 'limit', in: 'query', schema: { type: 'integer', minimum: 1, maximum: 100 } },
+            { name: 'offset', in: 'query', schema: { type: 'integer', minimum: 0 } },
+          ],
+          responses: {
+            '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicContentSummary') } } },
+            '401': { description: 'Missing/invalid API key', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } },
+            '403': { description: 'Missing scope', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } },
+            '429': { description: 'Rate limit exceeded' },
+          },
+        },
+      },
+      '/content/{slug}': {
+        get: {
+          summary: 'Get a single published content item',
+          security: [{ bearer: ['read:content'] }],
+          parameters: [
+            { name: 'slug', in: 'path', required: true, schema: { type: 'string' } },
+            { name: 'author', in: 'query', schema: { type: 'string' }, description: 'Disambiguate user-scoped slugs.' },
+          ],
+          responses: {
+            '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicContentSummary' } } } },
+            '404': { description: 'Not found', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } },
+          },
+        },
+      },
+      '/hubs': {
+        get: {
+          summary: 'List hubs',
+          security: [{ bearer: ['read:hubs'] }],
+          parameters: [
+            { name: 'type', in: 'query', schema: { type: 'string', enum: ['community', 'product', 'company'] } },
+            { name: 'search', in: 'query', schema: { type: 'string' } },
+            { name: 'limit', in: 'query', schema: { type: 'integer', minimum: 1, maximum: 100 } },
+            { name: 'offset', in: 'query', schema: { type: 'integer', minimum: 0 } },
+          ],
+          responses: {
+            '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicHub') } } },
+          },
+        },
+      },
+      '/hubs/{slug}': {
+        get: { summary: 'Get a hub', security: [{ bearer: ['read:hubs'] }], parameters: [{ name: 'slug', in: 'path', required: true, schema: { type: 'string' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicHub' } } } } } },
+      },
+      '/users': {
+        get: { summary: 'List public users', security: [{ bearer: ['read:users'] }], parameters: [{ name: 'q', in: 'query', schema: { type: 'string' } }, { name: 'limit', in: 'query', schema: { type: 'integer' } }, { name: 'offset', in: 'query', schema: { type: 'integer' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicUser') } } } } },
+      },
+      '/users/{username}': {
+        get: { summary: 'Get a public user profile', security: [{ bearer: ['read:users'] }], parameters: [{ name: 'username', in: 'path', required: true, schema: { type: 'string' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicUser' } } } } } },
+      },
+      '/instance': {
+        get: { summary: 'Instance metadata', security: [{ bearer: ['read:instance'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicInstance' } } } } } },
+      },
+      '/learn': {
+        get: { summary: 'List published learning paths', security: [{ bearer: ['read:learn'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicLearningPath') } } } } },
+      },
+      '/learn/{slug}': {
+        get: { summary: 'Get a learning path', security: [{ bearer: ['read:learn'] }], parameters: [{ name: 'slug', in: 'path', required: true, schema: { type: 'string' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicLearningPath' } } } } } },
+      },
+      '/events': {
+        get: { summary: 'List events (feature-gated)', security: [{ bearer: ['read:events'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicEvent') } } } } },
+      },
+      '/events/{slug}': {
+        get: { summary: 'Get an event', security: [{ bearer: ['read:events'] }], parameters: [{ name: 'slug', in: 'path', required: true, schema: { type: 'string' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicEvent' } } } } } },
+      },
+      '/contests': {
+        get: { summary: 'List contests (feature-gated)', security: [{ bearer: ['read:contests'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicContest') } } } } },
+      },
+      '/contests/{slug}': {
+        get: { summary: 'Get a contest', security: [{ bearer: ['read:contests'] }], parameters: [{ name: 'slug', in: 'path', required: true, schema: { type: 'string' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicContest' } } } } } },
+      },
+      '/videos': {
+        get: { summary: 'List videos (feature-gated)', security: [{ bearer: ['read:videos'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicVideo') } } } } },
+      },
+      '/videos/{id}': {
+        get: { summary: 'Get a video by id', security: [{ bearer: ['read:videos'] }], parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicVideo' } } } } } },
+      },
+      '/docs': {
+        get: { summary: 'List docs sites (feature-gated)', security: [{ bearer: ['read:docs'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicDocSite') } } } } },
+      },
+      '/docs/{slug}': {
+        get: { summary: 'Get a docs site', security: [{ bearer: ['read:docs'] }], parameters: [{ name: 'slug', in: 'path', required: true, schema: { type: 'string' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { $ref: '#/components/schemas/PublicDocSite' } } } } } },
+      },
+      '/tags': {
+        get: { summary: 'List tags with usage counts', security: [{ bearer: ['read:tags'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicTag') } } } } },
+      },
+      '/search': {
+        get: { summary: 'Search content', security: [{ bearer: ['read:search'] }], parameters: [{ name: 'q', in: 'query', required: true, schema: { type: 'string' } }, { name: 'type', in: 'query', schema: { type: 'string' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicContentSummary') } } } } },
+      },
+      '/openapi.json': {
+        get: { summary: 'This OpenAPI spec', responses: { '200': { description: 'OK' } } },
+      },
+    },
+  };
+});

package/server/api/public/v1/search/index.get.ts

@@ -0,0 +1,26 @@
+import { searchContent, toPublicContentSummary, type PublicContentRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  q: z.string().min(1).max(200),
+  type: z.enum(['project', 'blog', 'explainer']).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:search');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const { q, type, limit, offset } = parsed.data;
+  const db = useDB();
+  const config = useConfig();
+  const result = await searchContent(db, { query: q, type, limit, offset });
+  const domain = config.instance.domain;
+  const items = (result.items as unknown as PublicContentRow[])
+    .filter((r) => r.status === 'published' && !r.deletedAt)
+    .map((r) => toPublicContentSummary(r, domain));
+  return { items, total: result.total, limit, offset, query: q };
+});

package/server/api/public/v1/tags/index.get.ts

@@ -0,0 +1,39 @@
+import { toPublicTag, type PublicTagRow } from '@commonpub/server';
+import { tags, contentTags } from '@commonpub/schema';
+import { desc, sql } from 'drizzle-orm';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:tags');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const { limit, offset } = parsed.data;
+  const db = useDB();
+  const config = useConfig();
+
+  const rows = await db
+    .select({
+      id: tags.id,
+      name: tags.name,
+      slug: tags.slug,
+      usageCount: sql<number>`count(${contentTags.contentId})::int`,
+    })
+    .from(tags)
+    .leftJoin(contentTags, sql`${contentTags.tagId} = ${tags.id}`)
+    .groupBy(tags.id, tags.name, tags.slug)
+    .orderBy(desc(sql<number>`count(${contentTags.contentId})`), tags.name)
+    .limit(limit)
+    .offset(offset);
+
+  const [{ total }] = await db.select({ total: sql<number>`count(*)::int` }).from(tags);
+  const domain = config.instance.domain;
+  const items = (rows as unknown as PublicTagRow[]).map((r) => toPublicTag(r, domain));
+  return { items, total: total ?? 0, limit, offset };
+});

package/server/api/public/v1/videos/[id].get.ts

@@ -0,0 +1,18 @@
+import { getVideoById, toPublicVideo, isPublicVideo, type PublicVideoRow } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:videos');
+  requireFeature('video');
+  const id = getRouterParam(event, 'id');
+  if (!id) throw createError({ statusCode: 400, statusMessage: 'Missing id' });
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid id format' });
+  }
+  const db = useDB();
+  const config = useConfig();
+  const row = await getVideoById(db, id);
+  if (!row) throw createError({ statusCode: 404, statusMessage: 'Video not found' });
+  const casted = row as unknown as PublicVideoRow;
+  if (!isPublicVideo(casted)) throw createError({ statusCode: 404, statusMessage: 'Video not found' });
+  return toPublicVideo(casted, config.instance.domain);
+});

package/server/api/public/v1/videos/index.get.ts

@@ -0,0 +1,27 @@
+import { listVideos, toPublicVideo, isPublicVideo, type PublicVideoRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  categoryId: z.string().uuid().optional(),
+  authorId: z.string().uuid().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:videos');
+  requireFeature('video');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const filters = parsed.data;
+  const db = useDB();
+  const config = useConfig();
+  const result = await listVideos(db, filters);
+  const domain = config.instance.domain;
+  const items = (result.items as unknown as PublicVideoRow[])
+    .filter(isPublicVideo)
+    .map((r) => toPublicVideo(r, domain));
+  return { items, total: result.total, limit: filters.limit, offset: filters.offset };
+});