npm - koguma - Versions diffs - 0.4.0 - Mend

koguma 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/src/admin/dashboard.ts ADDED Viewed

@@ -0,0 +1,27 @@
+/**
+ * Koguma Admin Dashboard — served inline by the Worker.
+ *
+ * Imports the pre-built admin bundle from _bundle.ts (auto-generated
+ * by scripts/bundle-admin.ts after building the admin Vite app).
+ */
+import { adminJS, adminCSS } from "./_bundle.ts";
+export function adminHtml(siteName: string): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Admin — ${siteName}</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
+  <style>${adminCSS}</style>
+</head>
+<body>
+  <div id="root"></div>
+  <script>${adminJS}</script>
+</body>
+</html>`;
+}

package/src/api/router.ts ADDED Viewed

@@ -0,0 +1,357 @@
+/**
+ * Hono API router — auto-generates routes from the Koguma config.
+ *
+ * Public routes (no auth):
+ *   GET /api/content/:type          → list entries
+ *   GET /api/content/:type/:id      → get one entry
+ *   GET /api/media/:key             → serve media from R2
+ *
+ * Admin routes (auth required):
+ *   POST   /api/auth/login          → login
+ *   POST   /api/auth/logout         → logout
+ *   GET    /api/auth/me             → check session
+ *   GET    /api/admin/:type         → list entries
+ *   GET    /api/admin/:type/:id     → get one entry
+ *   POST   /api/admin/:type         → create entry
+ *   PUT    /api/admin/:type/:id     → update entry
+ *   DELETE /api/admin/:type/:id     → delete entry
+ *   GET    /api/admin/media         → list assets
+ *   POST   /api/admin/media         → upload asset
+ *   DELETE /api/admin/media/:id     → delete asset
+ *   GET    /api/admin/schema        → return content type schemas (for admin UI)
+ */
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { z } from 'zod/v4';
+import type { KogumaConfig, ContentTypeConfig } from '../config/define.ts';
+import {
+  getEntry,
+  getEntries,
+  createEntry,
+  updateEntry,
+  deleteEntry
+} from '../db/queries.ts';
+import { handleLogin, handleLogout, requireAuth } from '../auth/index.ts';
+import {
+  serveMedia,
+  uploadMedia,
+  listMedia,
+  deleteMedia
+} from '../media/index.ts';
+export function createApiRouter(config: KogumaConfig): Hono {
+  const app = new Hono();
+  // CORS for local dev
+  app.use('/api/*', cors());
+  // Content type lookup
+  const ctMap = new Map<string, ContentTypeConfig>();
+  for (const ct of config.contentTypes) {
+    ctMap.set(ct.id, ct);
+  }
+  // ── Reference resolution ─────────────────────────────────────────
+  // Resolves ref, refs, and image fields from flat IDs into nested objects.
+  // depth=1 resolves the entry's refs; depth=2 resolves refs-of-refs.
+  async function resolveEntry(
+    db: Parameters<typeof getEntry>[0],
+    entry: Record<string, unknown>,
+    ct: ContentTypeConfig,
+    depth = 1
+  ): Promise<Record<string, unknown>> {
+    if (depth < 1) return entry;
+    const resolved = { ...entry };
+    for (const [fieldId, meta] of Object.entries(ct.fieldMeta)) {
+      if (meta.fieldType === 'image') {
+        const assetId = entry[fieldId] as string | null;
+        if (assetId) {
+          const asset = await db
+            .prepare('SELECT * FROM _assets WHERE id = ?')
+            .bind(assetId)
+            .first();
+          resolved[fieldId] = asset ?? null;
+        }
+      } else if (meta.fieldType === 'reference' && meta.refContentType) {
+        const refId = entry[fieldId] as string | null;
+        if (refId) {
+          const refCt = ctMap.get(meta.refContentType);
+          if (refCt) {
+            const refEntry = await getEntry(db, refCt, refId);
+            resolved[fieldId] = refEntry
+              ? await resolveEntry(db, refEntry, refCt, depth - 1)
+              : null;
+          }
+        }
+      } else if (meta.fieldType === 'references' && meta.refContentType) {
+        const ids = entry[fieldId] as string[] | undefined;
+        if (ids?.length) {
+          const refCt = ctMap.get(meta.refContentType);
+          if (refCt) {
+            const items = await Promise.all(
+              ids.map(async id => {
+                const refEntry = await getEntry(db, refCt, id);
+                return refEntry
+                  ? resolveEntry(db, refEntry, refCt, depth - 1)
+                  : null;
+              })
+            );
+            resolved[fieldId] = items.filter(Boolean);
+          }
+        }
+      }
+    }
+    return resolved;
+  }
+  // ── Auth routes ──────────────────────────────────────────────────
+  app.post('/api/auth/login', handleLogin);
+  app.post('/api/auth/logout', handleLogout);
+  app.get('/api/auth/me', requireAuth, c => c.json({ authenticated: true }));
+  // ── Public content routes ────────────────────────────────────────
+  app.get('/api/content/:type', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof getEntries
+    >[0];
+    const includeDrafts = c.req.query('drafts') === 'true';
+    const entries = await getEntries(db, ct, { publishedOnly: !includeDrafts });
+    // Always resolve references for public API
+    const resolved = await Promise.all(
+      entries.map(e => resolveEntry(db, e, ct, 2))
+    );
+    return c.json({ entries: resolved });
+  });
+  app.get('/api/content/:type/:id', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof getEntry
+    >[0];
+    const entry = await getEntry(db, ct, c.req.param('id'));
+    if (!entry) return c.notFound();
+    const resolved = await resolveEntry(db, entry, ct, 2);
+    return c.json(resolved);
+  });
+  // ── Media serving (public) ───────────────────────────────────────
+  app.get('/api/media/:key', serveMedia);
+  // ── Admin routes (auth required) ─────────────────────────────────
+  app.use('/api/admin/*', requireAuth);
+  // Schema endpoint — admin UI uses this to render forms
+  app.get('/api/admin/schema', c => {
+    const schema = config.contentTypes.map(ct => ({
+      id: ct.id,
+      name: ct.name,
+      displayField: ct.displayField,
+      singleton: ct.singleton ?? false,
+      fieldMeta: ct.fieldMeta,
+      groups: ct.groups.map(g => ({
+        groupId: g.groupId,
+        name: g.name,
+        helpText: g.helpText,
+        collapsed: g.collapsed,
+        fieldIds: Object.keys(g.fields)
+      }))
+    }));
+    return c.json({ contentTypes: schema });
+  });
+  // ── Media management (admin) — must be before :type catch-all ────
+  app.get('/api/admin/media', listMedia);
+  app.post('/api/admin/media', uploadMedia);
+  app.delete('/api/admin/media/:id', deleteMedia);
+  // CRUD
+  app.get('/api/admin/:type', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof getEntries
+    >[0];
+    const entries = await getEntries(db, ct);
+    return c.json({ entries });
+  });
+  app.get('/api/admin/:type/:id', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof getEntry
+    >[0];
+    const entry = await getEntry(db, ct, c.req.param('id'));
+    if (!entry) return c.notFound();
+    return c.json(entry);
+  });
+  app.post('/api/admin/:type', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof createEntry
+    >[0];
+    const data = await c.req.json();
+    // D1 stores booleans as 0/1 — coerce back before validation
+    for (const [fid, meta] of Object.entries(ct.fieldMeta)) {
+      if (
+        meta.fieldType === 'boolean' &&
+        fid in data &&
+        typeof data[fid] === 'number'
+      ) {
+        data[fid] = Boolean(data[fid]);
+      }
+    }
+    // Validate with Zod schema
+    const result = ct.schema.safeParse(data);
+    if (!result.success) {
+      const issues = (result.error as z.ZodError).issues.map(issue => ({
+        field: issue.path.join('.'),
+        message: issue.message
+      }));
+      return c.json({ error: 'Validation failed', issues }, 422);
+    }
+    const entry = await createEntry(db, ct, data);
+    return c.json(entry, 201);
+  });
+  app.put('/api/admin/:type/:id', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof updateEntry
+    >[0];
+    const data = await c.req.json();
+    // D1 stores booleans as 0/1 — coerce back before validation
+    for (const [fid, meta] of Object.entries(ct.fieldMeta)) {
+      if (
+        meta.fieldType === 'boolean' &&
+        fid in data &&
+        typeof data[fid] === 'number'
+      ) {
+        data[fid] = Boolean(data[fid]);
+      }
+    }
+    // Partial validation — only validate fields present in request
+    const result = (ct.schema as z.ZodObject<Record<string, z.ZodType>>)
+      .partial()
+      .safeParse(data);
+    if (!result.success) {
+      const issues = (result.error as z.ZodError).issues.map(issue => ({
+        field: issue.path.join('.'),
+        message: issue.message
+      }));
+      return c.json({ error: 'Validation failed', issues }, 422);
+    }
+    const entry = await updateEntry(db, ct, c.req.param('id'), data);
+    if (!entry) return c.notFound();
+    return c.json(entry);
+  });
+  app.put('/api/admin/:type', async c => {
+    // For singleton types — update the first (only) entry
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof getEntries
+    >[0];
+    const entries = await getEntries(db, ct);
+    if (entries.length === 0) return c.json({ error: 'No entry found' }, 404);
+    const data = await c.req.json();
+    const entry = await updateEntry(
+      db as Parameters<typeof updateEntry>[0],
+      ct,
+      entries[0]!.id as string,
+      data
+    );
+    return c.json(entry);
+  });
+  app.delete('/api/admin/:type/:id', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof deleteEntry
+    >[0];
+    await deleteEntry(db, ct, c.req.param('id'));
+    return c.json({ ok: true });
+  });
+  // Publish / Unpublish convenience endpoints
+  app.post('/api/admin/:type/:id/publish', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof updateEntry
+    >[0];
+    const entry = await updateEntry(db, ct, c.req.param('id'), {
+      status: 'published',
+      publishAt: null // clear scheduled time — publish immediately
+    });
+    if (!entry) return c.notFound();
+    return c.json(entry);
+  });
+  app.post('/api/admin/:type/:id/unpublish', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof updateEntry
+    >[0];
+    const entry = await updateEntry(db, ct, c.req.param('id'), {
+      status: 'draft',
+      publishAt: null // clear scheduled time
+    });
+    if (!entry) return c.notFound();
+    return c.json(entry);
+  });
+  // Schedule — set a future publish time
+  app.post('/api/admin/:type/:id/schedule', async c => {
+    const ct = ctMap.get(c.req.param('type'));
+    if (!ct) return c.json({ error: 'Unknown content type' }, 404);
+    const db = (c.env as Record<string, unknown>).DB as Parameters<
+      typeof updateEntry
+    >[0];
+    const body = await c.req.json<{ publishAt: string }>();
+    if (!body.publishAt) {
+      return c.json({ error: 'publishAt is required' }, 400);
+    }
+    const entry = await updateEntry(db, ct, c.req.param('id'), {
+      status: 'published',
+      publishAt: body.publishAt
+    });
+    if (!entry) return c.notFound();
+    return c.json(entry);
+  });
+  return app;
+}

package/src/auth/index.ts ADDED Viewed

@@ -0,0 +1,138 @@
+/**
+ * Auth middleware — simple password-based login with cookie sessions.
+ *
+ * v1: Single shared password stored as KOGUMA_SECRET Wrangler secret.
+ * Sessions use HMAC-signed cookies (no external dependencies).
+ */
+import type { Context, Next } from "hono";
+const SESSION_COOKIE = "koguma_session";
+const SESSION_MAX_AGE = 7 * 24 * 60 * 60; // 7 days
+// ── HMAC signing ─────────────────────────────────────────────────────
+async function hmacSign(payload: string, secret: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  const sig = btoa(String.fromCharCode(...new Uint8Array(signature)));
+  return `${payload}.${sig}`;
+}
+async function hmacVerify(token: string, secret: string): Promise<string | null> {
+  const lastDot = token.lastIndexOf(".");
+  if (lastDot === -1) return null;
+  const payload = token.slice(0, lastDot);
+  const expected = await hmacSign(payload, secret);
+  // Constant-time compare
+  if (expected.length !== token.length) return null;
+  let diff = 0;
+  for (let i = 0; i < expected.length; i++) {
+    diff |= expected.charCodeAt(i) ^ token.charCodeAt(i);
+  }
+  return diff === 0 ? payload : null;
+}
+// ── Cookie helpers ───────────────────────────────────────────────────
+function getCookie(c: Context, name: string): string | undefined {
+  const header = c.req.header("cookie") ?? "";
+  const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+  return match?.[1];
+}
+function setCookie(c: Context, name: string, value: string, maxAge: number) {
+  c.header(
+    "Set-Cookie",
+    `${name}=${value}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`,
+  );
+}
+function clearCookie(c: Context, name: string) {
+  c.header(
+    "Set-Cookie",
+    `${name}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`,
+  );
+}
+// ── Login handler ────────────────────────────────────────────────────
+export async function handleLogin(c: Context): Promise<Response> {
+  const secret = (c.env as Record<string, string>).KOGUMA_SECRET;
+  if (!secret) {
+    return c.json({ error: "KOGUMA_SECRET not configured" }, 500);
+  }
+  const body = await c.req.json<{ password?: string }>();
+  if (!body.password) {
+    return c.json({ error: "Password required" }, 400);
+  }
+  // Constant-time compare
+  const encoder = new TextEncoder();
+  const a = encoder.encode(body.password);
+  const b = encoder.encode(secret);
+  if (a.length !== b.length) {
+    return c.json({ error: "Invalid password" }, 401);
+  }
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a[i]! ^ b[i]!;
+  }
+  if (diff !== 0) {
+    return c.json({ error: "Invalid password" }, 401);
+  }
+  // Create signed session token
+  const payload = JSON.stringify({
+    exp: Math.floor(Date.now() / 1000) + SESSION_MAX_AGE,
+  });
+  const token = await hmacSign(payload, secret);
+  setCookie(c, SESSION_COOKIE, token, SESSION_MAX_AGE);
+  return c.json({ ok: true });
+}
+// ── Logout handler ───────────────────────────────────────────────────
+export function handleLogout(c: Context): Response {
+  clearCookie(c, SESSION_COOKIE);
+  return c.json({ ok: true });
+}
+// ── Auth middleware ──────────────────────────────────────────────────
+export async function requireAuth(c: Context, next: Next): Promise<Response | void> {
+  const secret = (c.env as Record<string, string>).KOGUMA_SECRET;
+  if (!secret) {
+    return c.json({ error: "KOGUMA_SECRET not configured" }, 500);
+  }
+  const token = getCookie(c, SESSION_COOKIE);
+  if (!token) {
+    return c.json({ error: "Not authenticated" }, 401);
+  }
+  const payload = await hmacVerify(token, secret);
+  if (!payload) {
+    return c.json({ error: "Invalid session" }, 401);
+  }
+  try {
+    const data = JSON.parse(payload) as { exp: number };
+    if (data.exp < Math.floor(Date.now() / 1000)) {
+      clearCookie(c, SESSION_COOKIE);
+      return c.json({ error: "Session expired" }, 401);
+    }
+  } catch {
+    return c.json({ error: "Invalid session" }, 401);
+  }
+  await next();
+}

package/src/client/index.ts ADDED Viewed

@@ -0,0 +1,61 @@
+/**
+ * Koguma browser client — typed fetch wrapper for the CMS API.
+ *
+ * Usage:
+ *   import { createClient } from "koguma/client";
+ *   const koguma = createClient();
+ *   const page = await koguma.get<FourDirectionsPage>("fourDirectionsPage", "single");
+ *   const cards = await koguma.list<FeatureCard>("featureCard");
+ */
+interface KogumaClientOptions {
+  /** Base URL for the API. Defaults to "" (same origin — works in Cloudflare Workers). */
+  baseUrl?: string;
+}
+export interface KogumaClient {
+  /** Fetch a single entry by ID (or "single" for singleton types) */
+  get<T = Record<string, unknown>>(contentType: string, id: string): Promise<T>;
+  /** Fetch all entries of a given type */
+  list<T = Record<string, unknown>>(contentType: string): Promise<T[]>;
+}
+export function createClient(opts: KogumaClientOptions = {}): KogumaClient {
+  const base = opts.baseUrl ?? "";
+  async function apiFetch<T>(url: string): Promise<T> {
+    const res = await fetch(`${base}${url}`);
+    if (!res.ok) {
+      throw new Error(`Koguma API error: ${res.status} ${res.statusText} (${url})`);
+    }
+    return res.json() as Promise<T>;
+  }
+  return {
+    async get<T>(contentType: string, id: string): Promise<T> {
+      // "single" is a convenience alias for singleton types
+      if (id === "single") {
+        const data = await apiFetch<{ entries: T[] }>(`/api/content/${contentType}`);
+        const entry = data.entries[0];
+        if (!entry) throw new Error(`No entry found for ${contentType}`);
+        return entry;
+      }
+      return apiFetch<T>(`/api/content/${contentType}/${id}`);
+    },
+    async list<T>(contentType: string): Promise<T[]> {
+      const data = await apiFetch<{ entries: T[] }>(`/api/content/${contentType}`);
+      return data.entries;
+    },
+  };
+}
+/** Singleton client — shared across the app */
+let _client: KogumaClient | null = null;
+export function getClient(): KogumaClient {
+  if (!_client) {
+    _client = createClient();
+  }
+  return _client;
+}