npm - @takuhon/api - Versions diffs - 0.16.0 → 0.17.0 - Mend

@takuhon/api 0.16.0 → 0.17.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 (5) hide show

package/README.md CHANGED Viewed

@@ -4,7 +4,8 @@ Hono-based HTTP route handlers, RFC 7807 Problem Details error envelope, and res
 Ships:
-- `createPublicApp({ storage })` — public profile read endpoints, JSON-LD output, `/.well-known/takuhon.json`
+- `createPublicApp({ storage })` — the server-rendered profile page at `GET /` (and `/<locale>/`) with Schema.org JSON-LD embedded in the HTML, plus the public read endpoints (`/api/profile`, `/api/jsonld`, `/api/schema`, `/takuhon.json`) and `/.well-known/takuhon.json`
+- `renderProfileHtml` / `generateSite` / `renderCvHtml` — pure, `@takuhon/core`-only static HTML rendering (no DOM, no bundler) shared by the `GET /` route and `@takuhon/cli`'s `build` / `dev`
 - `createAdminApiApp({ storage, bearerToken, originAllowlist, cachePurger, auditLogger })` — `PUT`/`DELETE /api/admin/profile` with optimistic locking (`If-Match`), audit logging, and edge-cache purging
 - `createAdminUiApp()` — minimal HTML admin editor (token + JSON textarea + Save/Delete)
 - `CachePurger` and `AuditLogger` dependency-injection interfaces (with `noopCachePurger` / `noopAuditLogger` no-op implementations)

package/dist/index.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 import { Context, Hono } from 'hono';
 import { ContentfulStatusCode } from 'hono/utils/http-status';
-import { TakuhonStorage, Takuhon, ActivityStorage, TakuhonAssetStorage } from '@takuhon/core';
+import { TakuhonStorage, Takuhon, ActivityStorage, TakuhonAssetStorage, LocalizedTakuhon, ActivitySnapshot, NormalizedTakuhon, CvDocument } from '@takuhon/core';
 export { applyPublicPrivacyFilter } from '@takuhon/core';
 /**
@@ -235,4 +235,139 @@ declare function createAdminUiApp(): Hono;
  */
 declare function adminAssetSecurityHeaders(): Record<string, string>;
-export { type AdminApiAppDeps, type AuditEvent, type AuditEventType, type AuditLogger, type BuildProblemInput, type CachePurger, ERROR_SLUGS, type ErrorSlug, LOCALE_AWARE_REMAINDERS, type ProblemDetails, type ProblemFieldError, type ProblemResponseInput, type PublicAppDeps, adminAssetSecurityHeaders, buildProblem, createAdminApiApp, createAdminUiApp, createPublicApp, localePrefixGetPath, noopAuditLogger, noopCachePurger, pathLocaleFromUrl, problemResponse, stripLocalePrefix };
+/**
+ * Pure HTML helpers shared by the static-site renderer ({@link
+ * import('./build-html.js')}) and the CV renderer ({@link
+ * import('./cv-html.js')}). All are string-in / string-out with no I/O, so they
+ * stay unit-testable and keep both renderers' escaping behavior identical.
+ */
+/** Escape text for use in HTML element content or double/single-quoted attributes. */
+declare function escapeHtml(value: string): string;
+/**
+ * Pure HTML rendering for `takuhon build`.
+ *
+ * {@link renderProfileHtml} turns one locale-resolved {@link LocalizedTakuhon}
+ * into a complete, self-contained static HTML document: semantic markup for
+ * every profile section, an inline stylesheet, optional Schema.org JSON-LD,
+ * and the `<head>` metadata (`<title>`, description, canonical, hreflang
+ * alternates) the caller supplies.
+ *
+ * This is a deliberately separate, simpler surface from the React
+ * `@takuhon/ui` (which is delivered as CSS-Modules components needing a
+ * bundler). It reuses only `@takuhon/core` and has no DOM/browser dependency,
+ * so it renders in plain Node and is unit-testable as a pure string function.
+ *
+ * Security: every piece of profile-derived text is escaped before it reaches
+ * the markup ({@link escapeHtml}), and the JSON-LD payload is `<`/`>`/`&`
+ * unicode-escaped so it cannot break out of its `<script>` element.
+ */
+/** One entry in the human-facing locale switcher. */
+interface LocaleLink {
+    locale: string;
+    href: string;
+    current: boolean;
+}
+/** One `<link rel="alternate" hreflang>` entry. */
+interface Alternate {
+    hreflang: string;
+    href: string;
+}
+interface RenderInput {
+    /** The locale-resolved document to render. */
+    localized: LocalizedTakuhon;
+    /** Absolute canonical URL for this page (only when `--base-url` was given). */
+    canonicalUrl?: string;
+    /** hreflang alternates (empty when no base URL is available). */
+    alternates: readonly Alternate[];
+    /** Human locale switcher links (rendered only when more than one locale). */
+    localeNav: readonly LocaleLink[];
+    /** Whether to emit Schema.org JSON-LD (mirrors `settings.enableJsonLd`). */
+    jsonLd: boolean;
+    /**
+     * Synced developer-activity snapshot, rendered as a self-owned inline SVG
+     * section. The caller gates it on `settings.activity.enabled`; an absent (or
+     * metric-less) snapshot omits the section entirely.
+     */
+    activitySnapshot?: ActivitySnapshot;
+}
+/** Render a complete static HTML document for one locale-resolved profile. */
+declare function renderProfileHtml(input: RenderInput): string;
+/**
+ * Shared static-site generation for `takuhon build` and `takuhon dev`.
+ *
+ * {@link generateSite} turns one validated, normalized, privacy-filtered profile
+ * into the full set of pages the static surface exposes: one per available
+ * locale. `build` writes each page's {@link SitePage.file} to disk; `dev` serves
+ * each page's {@link SitePage.route} from memory. Keeping the per-locale loop,
+ * the locale switcher links, and the canonical/hreflang logic here means both
+ * commands share a single source of truth for the site's structure — the only
+ * difference between them is disk write vs. in-memory serve.
+ *
+ * This reuses `@takuhon/core` only (validate/normalize/resolve happen upstream;
+ * this module just resolves each locale and renders), so it stays bundler-free
+ * and unit-testable as a pure function.
+ */
+/** One generated page: a serve route, a relative output file, and its HTML. */
+interface SitePage {
+    /** URL path used by `dev` (default locale at `/`, others at `/<locale>/`). */
+    readonly route: string;
+    /** Output path used by `build`, relative to the output dir. */
+    readonly file: string;
+    /** Rendered HTML document. */
+    readonly html: string;
+}
+interface GenerateOptions {
+    /**
+     * Site origin (e.g. `https://me.example`). When set, pages carry absolute
+     * canonical + hreflang links; when absent those are omitted (the human locale
+     * switcher is always relative either way).
+     */
+    readonly baseUrl?: string;
+    /**
+     * Synced developer-activity snapshot (the `activity.json` beside the
+     * profile). Rendered as an inline-SVG section only while
+     * `settings.activity.enabled` is true — the same opt-in gate the public
+     * `GET /api/activity` applies — so disabling the feature drops the section
+     * even if a stale snapshot remains on disk. The snapshot is locale-agnostic
+     * and shared by every page.
+     */
+    readonly activitySnapshot?: ActivitySnapshot | null;
+    /**
+     * Also emit a print-ready CV/résumé page per locale (the default locale at
+     * `cv.html` / route `/cv/`, others at `<locale>/cv.html` / `/<locale>/cv/`).
+     * `takuhon build` gates this behind `--cv`; `takuhon dev` always enables it so
+     * the page is previewable. Off by default, so a plain build is unchanged.
+     */
+    readonly cv?: boolean;
+}
+/**
+ * Generate every page for a profile: the default locale first, then the rest,
+ * de-duplicated. Schema.org JSON-LD is emitted unless `settings.enableJsonLd`
+ * is explicitly `false`.
+ */
+declare function generateSite(profile: NormalizedTakuhon, options?: GenerateOptions): SitePage[];
+/**
+ * Pure HTML rendering of a {@link CvDocument} for `takuhon build --cv`.
+ *
+ * {@link renderCvHtml} turns one locale-resolved CV (from `@takuhon/core`'s
+ * {@link deriveCv}) into a complete, self-contained static HTML résumé: an
+ * inline stylesheet sized for A4 with an `@media print` block, so the page
+ * reads well on screen and the browser's "Save as PDF" produces a clean,
+ * single-column résumé. No external resources are referenced, so the page works
+ * under a strict `img-src 'self'` / no-network policy (the same self-owned
+ * stance the profile page and the activity card take).
+ *
+ * Security: every CV-derived string is escaped before it reaches the markup
+ * ({@link escapeHtml}), and any URL is scheme-checked ({@link safeUrl}) so a
+ * hostile document cannot smuggle a `javascript:` href into the résumé.
+ */
+/** Render a complete static HTML résumé document for one locale-resolved CV. */
+declare function renderCvHtml(cv: CvDocument): string;
+export { type AdminApiAppDeps, type Alternate, type AuditEvent, type AuditEventType, type AuditLogger, type BuildProblemInput, type CachePurger, ERROR_SLUGS, type ErrorSlug, type GenerateOptions, LOCALE_AWARE_REMAINDERS, type LocaleLink, type ProblemDetails, type ProblemFieldError, type ProblemResponseInput, type PublicAppDeps, type RenderInput, type SitePage, adminAssetSecurityHeaders, buildProblem, createAdminApiApp, createAdminUiApp, createPublicApp, escapeHtml, generateSite, localePrefixGetPath, noopAuditLogger, noopCachePurger, pathLocaleFromUrl, problemResponse, renderCvHtml, renderProfileHtml, stripLocalePrefix };