@ingram-tech/nk-blog 0.1.4 → 0.1.6

package/src/sources/github.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import type { BlogSource, RawPostFile } from "../blog.js";
+import { assertResponseOk } from "../http.js";
+import { keys } from "../keys.js";
+
+export interface GitHubRepoConfig {
+	owner: string;
+	repo: string;
+	/** Branch, tag, or commit; defaults to the repo's default branch. */
+	ref?: string;
+	/** Content directory inside the repo, e.g. "content/blog". */
+	dir: string;
+	/** Falls back to the GITHUB_TOKEN env var. */
+	token?: string;
+}
+
+const API = "https://api.github.com";
+
+export function githubHeaders(token: string | undefined): Record<string, string> {
+	const resolved = token ?? keys().GITHUB_TOKEN;
+	return {
+		accept: "application/vnd.github+json",
+		"x-github-api-version": "2022-11-28",
+		"user-agent": "nk-blog",
+		...(resolved ? { authorization: `Bearer ${resolved}` } : {}),
+	};
+}
+
+const treeSchema = z.object({
+	truncated: z.boolean(),
+	tree: z.array(
+		z.object({
+			path: z.string(),
+			type: z.string(),
+			sha: z.string(),
+		}),
+	),
+});
+
+const blobSchema = z.object({
+	content: z.string(),
+	encoding: z.literal("base64"),
+});
+
+/**
+ * Read a repo's posts over the GitHub API — the admin publisher's read path
+ * (list a target's real posts; reconcile instead of blind-append). One Trees
+ * call for the listing, then batched blob fetches: never per-file `contents`
+ * round-trips.
+ */
+export function githubSource(config: GitHubRepoConfig): BlogSource {
+	return {
+		async load(): Promise<RawPostFile[]> {
+			const headers = githubHeaders(config.token);
+			const base = `${API}/repos/${config.owner}/${config.repo}`;
+			const ref = config.ref ?? "HEAD";
+
+			const treeResponse = await fetch(
+				`${base}/git/trees/${encodeURIComponent(ref)}?recursive=1`,
+				{ headers },
+			);
+			await assertResponseOk(
+				treeResponse,
+				`nk-blog: listing ${config.owner}/${config.repo}@${ref}`,
+			);
+			const { tree, truncated } = treeSchema.parse(await treeResponse.json());
+			if (truncated) {
+				throw new Error(
+					`nk-blog: git tree for ${config.owner}/${config.repo} is truncated; narrow \`dir\``,
+				);
+			}
+
+			const prefix = `${config.dir.replace(/\/$/, "")}/`;
+			const files = tree.filter(
+				(entry) =>
+					entry.type === "blob" &&
+					entry.path.startsWith(prefix) &&
+					/\.mdx?$/.test(entry.path),
+			);
+
+			// Bounded concurrency: an unbounded Promise.all over every post blob
+			// hammers the API and trips secondary rate limits on large blogs.
+			const CONCURRENCY = 8;
+			const results: { name: string; content: string }[] = [];
+			for (let i = 0; i < files.length; i += CONCURRENCY) {
+				const chunk = await Promise.all(
+					files.slice(i, i + CONCURRENCY).map(async (entry) => {
+						const blobResponse = await fetch(
+							`${base}/git/blobs/${entry.sha}`,
+							{
+								headers,
+							},
+						);
+						await assertResponseOk(
+							blobResponse,
+							`nk-blog: reading ${entry.path}`,
+						);
+						const blob = blobSchema.parse(await blobResponse.json());
+						return {
+							name: entry.path.slice(prefix.length),
+							content: Buffer.from(blob.content, "base64").toString(
+								"utf8",
+							),
+						};
+					}),
+				);
+				results.push(...chunk);
+			}
+			return results;
+		},
+	};
+}

package/src/sources/publish.ts

@@ -0,0 +1,103 @@
+import matter from "gray-matter";
+import { z } from "zod";
+import {
+	blogFrontmatterSchema,
+	type BlogFrontmatterInput,
+	slugPattern,
+} from "../schema.js";
+import type { PostFormat } from "../types.js";
+import { assertResponseOk } from "../http.js";
+import { githubHeaders, type GitHubRepoConfig } from "./github.js";
+
+const API = "https://api.github.com";
+
+/** Canonical on-disk form of a post: YAML frontmatter + body, one trailing \n. */
+export function serializePost(frontmatter: BlogFrontmatterInput, body: string): string {
+	// Validate before serializing so admin can never commit a file the sites'
+	// readers would reject at build time.
+	blogFrontmatterSchema.parse(frontmatter);
+	return `${matter.stringify(`\n${body.trim()}\n`, frontmatter).trim()}\n`;
+}
+
+export interface PublishPostInput {
+	slug: string;
+	frontmatter: BlogFrontmatterInput;
+	body: string;
+	/** Admin's automated path emits "md" (data, never code) — the default. */
+	format?: PostFormat;
+	message?: string;
+	/** Commit to this branch (e.g. for a draft/preview PR) instead of the ref. */
+	branch?: string;
+	/** Update an existing post instead of failing the slug-collision check. */
+	overwrite?: boolean;
+}
+
+const putResponseSchema = z.object({
+	content: z.object({ path: z.string(), sha: z.string() }),
+	commit: z.object({ sha: z.string(), html_url: z.string().optional() }),
+});
+
+export type PublishedPost = z.infer<typeof putResponseSchema>;
+
+/**
+ * Publish a post by committing one content file to the target repo — the
+ * entire replacement for admin's buildPostsJson/buildMdx machinery.
+ */
+export async function publishPost(
+	target: GitHubRepoConfig,
+	input: PublishPostInput,
+): Promise<PublishedPost> {
+	if (!slugPattern.test(input.slug)) {
+		// The slug lands in a repo file path — anything looser is a traversal
+		// vector (`../.github/workflows/x`) and breaks routes/RSS URLs anyway.
+		throw new Error(`nk-blog: invalid slug "${input.slug}"`);
+	}
+	const frontmatterSlug = input.frontmatter.slug;
+	if (frontmatterSlug !== undefined && frontmatterSlug !== input.slug) {
+		// The reader routes by the frontmatter override, so a mismatch defeats
+		// the filename-based collision check below and can break the target
+		// site's build with a duplicate-slug error.
+		throw new Error(
+			`nk-blog: frontmatter slug "${frontmatterSlug}" does not match publish slug "${input.slug}"`,
+		);
+	}
+	const headers = githubHeaders(target.token);
+	const base = `${API}/repos/${target.owner}/${target.repo}`;
+	const filePath = `${target.dir.replace(/\/$/, "")}/${input.slug}.${
+		input.format ?? "md"
+	}`;
+	const branch = input.branch ?? target.ref;
+	const refQuery = branch ? `?ref=${encodeURIComponent(branch)}` : "";
+
+	// Slug-collision check (and the sha needed when overwriting).
+	const existing = await fetch(`${base}/contents/${filePath}${refQuery}`, {
+		headers,
+	});
+	let existingSha: string | undefined;
+	if (existing.ok) {
+		if (!input.overwrite) {
+			throw new Error(
+				`nk-blog: ${filePath} already exists in ${target.owner}/${target.repo}`,
+			);
+		}
+		existingSha = z.object({ sha: z.string() }).parse(await existing.json()).sha;
+	} else if (existing.status !== 404) {
+		await assertResponseOk(existing, `nk-blog: checking ${filePath}`);
+	}
+
+	const response = await fetch(`${base}/contents/${filePath}`, {
+		method: "PUT",
+		headers: { ...headers, "content-type": "application/json" },
+		body: JSON.stringify({
+			message: input.message ?? `content: publish ${input.slug}`,
+			content: Buffer.from(
+				serializePost(input.frontmatter, input.body),
+				"utf8",
+			).toString("base64"),
+			...(branch ? { branch } : {}),
+			...(existingSha ? { sha: existingSha } : {}),
+		}),
+	});
+	await assertResponseOk(response, `nk-blog: publishing ${filePath}`);
+	return putResponseSchema.parse(await response.json());
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+export type PostFormat = "md" | "mdx";
+
+/** Everything a listing page needs — no body. */
+export interface BlogPostPreview {
+	slug: string;
+	title: string;
+	seoTitle?: string;
+	description: string;
+	/** ISO 8601. */
+	date: string;
+	/** ISO 8601; set when the post declares an `updated` date. */
+	updated?: string;
+	authors: string[];
+	/** First author — convenience for single-byline layouts. */
+	author: string;
+	category?: string;
+	tags: string[];
+	image?: string;
+	draft: boolean;
+	featured: boolean;
+	/** Reserved for i18n'd blogs; not interpreted by the reader yet. */
+	lang?: string;
+	/** Reserved canonical-URL override for syndicated posts. */
+	canonical?: string;
+	format: PostFormat;
+	readingTimeMinutes: number;
+	/** e.g. "5 min read" — derived from the body, never authored. */
+	readTime: string;
+}
+
+/** A full post: the preview fields plus the body (frontmatter stripped). */
+export interface BlogPost extends BlogPostPreview {
+	content: string;
+}

package/src/unstyled/callout.tsx

@@ -0,0 +1,18 @@
+import type { CalloutProps } from "../contract.js";
+
+/**
+ * Unstyled default. Semantic structure only — style it from the site via the
+ * data attributes, or replace it wholesale. No visual props beyond className,
+ * ever (the bright line that keeps "unstyled" from eroding into a theme).
+ */
+export const Callout: React.FC<CalloutProps> = ({
+	variant = "note",
+	title,
+	className,
+	children,
+}) => (
+	<aside data-callout={variant} className={className}>
+		{title ? <p data-callout-title>{title}</p> : null}
+		<div data-callout-body>{children}</div>
+	</aside>
+);

package/src/unstyled/figure.tsx

@@ -0,0 +1,30 @@
+import type { FigureProps } from "../contract.js";
+
+const toDimension = (value: number | string | undefined): number | undefined =>
+	typeof value === "string" ? Number(value) : value;
+
+/**
+ * Unstyled captioned image: correct semantics (figure/figcaption), lazy
+ * loading, and explicit dimensions when given (CLS). Sites wanting
+ * next/image replace this wholesale.
+ */
+export const Figure: React.FC<FigureProps> = ({
+	src,
+	alt,
+	caption,
+	width,
+	height,
+	className,
+}) => (
+	<figure className={className}>
+		<img
+			src={src}
+			alt={alt}
+			width={toDimension(width)}
+			height={toDimension(height)}
+			loading="lazy"
+			decoding="async"
+		/>
+		{caption ? <figcaption>{caption}</figcaption> : null}
+	</figure>
+);

package/src/unstyled/index.ts

@@ -0,0 +1,24 @@
+import { defineBlogComponents } from "../contract.js";
+import { Callout } from "./callout.js";
+import { Figure } from "./figure.js";
+import { NewsletterSubscribe } from "./newsletter-subscribe.js";
+import { Tweet } from "./tweet.js";
+import { YouTube } from "./youtube.js";
+
+export { Callout, Figure, NewsletterSubscribe, Tweet, YouTube };
+
+/**
+ * The complete default registry. A site's whole obligation is:
+ *
+ *   export const blogComponents = defineBlogComponents({
+ *       ...unstyled,
+ *       Callout: BrandCallout, // replaced wholesale where the brand cares
+ *   });
+ */
+export const unstyled = defineBlogComponents({
+	Callout,
+	Figure,
+	YouTube,
+	Tweet,
+	NewsletterSubscribe,
+});

package/src/unstyled/newsletter-subscribe.tsx

@@ -0,0 +1,23 @@
+import type { NewsletterSubscribeProps } from "../contract.js";
+
+/**
+ * Plain HTML form POSTing to the injected endpoint — works with zero client
+ * JS. The package never bakes in a newsletter backend.
+ */
+export const NewsletterSubscribe: React.FC<NewsletterSubscribeProps> = ({
+	action,
+	placeholder,
+	buttonLabel,
+	className,
+}) => (
+	<form action={action} method="post" className={className}>
+		<input
+			type="email"
+			name="email"
+			required
+			placeholder={placeholder ?? "you@example.com"}
+			aria-label="Email address"
+		/>
+		<button type="submit">{buttonLabel ?? "Subscribe"}</button>
+	</form>
+);

package/src/unstyled/tweet.tsx

@@ -0,0 +1,12 @@
+import type { TweetProps } from "../contract.js";
+
+/**
+ * Zero-JS default: the standard `twitter-tweet` blockquote, progressively
+ * enhanced if the site loads the platform widget script — otherwise it
+ * degrades to a plain link. No data fetching in the package.
+ */
+export const Tweet: React.FC<TweetProps> = ({ id, className }) => (
+	<blockquote className={["twitter-tweet", className].filter(Boolean).join(" ")}>
+		<a href={`https://twitter.com/i/status/${encodeURIComponent(id)}`}>View post</a>
+	</blockquote>
+);

package/src/unstyled/youtube.tsx

@@ -0,0 +1,24 @@
+import type { YouTubeProps } from "../contract.js";
+
+/**
+ * Privacy-enhanced (youtube-nocookie), lazy-loaded embed with a stable 16:9
+ * box (CLS). The inline aspect-ratio is behavior, not styling.
+ */
+export const YouTube: React.FC<YouTubeProps> = ({ id, title, start, className }) => {
+	const startSeconds = typeof start === "string" ? Number(start) : start;
+	const src = `https://www.youtube-nocookie.com/embed/${encodeURIComponent(id)}${
+		startSeconds ? `?start=${startSeconds}` : ""
+	}`;
+	return (
+		<iframe
+			src={src}
+			title={title ?? "YouTube video"}
+			loading="lazy"
+			allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+			allowFullScreen
+			referrerPolicy="strict-origin-when-cross-origin"
+			className={className}
+			style={{ aspectRatio: "16 / 9", width: "100%", border: 0 }}
+		/>
+	);
+};