@happyvertical/smrt-content 0.43.9 → 0.44.0

package/dist/chunks/contents-BrGxWH3s.js

@@ -0,0 +1,612 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { D as serializeFact, E as serializeContent, J as getEffectiveContentGovernanceConfig, Q as loadPersistedContentGovernanceDefinitions, nt as resolveEffectiveContentGovernance, w as Content, x as executeContentQuery } from "./content-query-B4cHfrig.js";
+import { htmlToMarkdown, resolveBodyFormat } from "../body-format.js";
+import { SmrtCollection, smrt } from "@happyvertical/smrt-core";
+import { queryGlobal, queryWithGlobals } from "@happyvertical/smrt-tenancy";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fetchDocument } from "@happyvertical/documents";
+import { ensureDirectoryExists } from "@happyvertical/files";
+import { createLogger } from "@happyvertical/logger";
+import { makeSlug } from "@happyvertical/utils";
+import YAML from "yaml";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+//#region src/safe-remote-url.ts
+async function defaultResolveHostname(hostname) {
+	return lookup(hostname, {
+		all: true,
+		verbatim: false
+	});
+}
+function isBlockedIPv4(address) {
+	const parts = address.split(".");
+	if (parts.length !== 4) return true;
+	const octets = parts.map((part) => /^\d{1,3}$/.test(part) ? Number(part) : NaN);
+	if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+	const [first, second] = octets;
+	return first === 0 || first === 10 || first === 127 || first >= 224 || first === 100 && second >= 64 && second <= 127 || first === 169 && second === 254 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168 || first === 198 && (second === 18 || second === 19);
+}
+function expandIPv6(address) {
+	let work = address.toLowerCase().replace(/^\[|\]$/g, "");
+	if (work.includes(".")) {
+		const m = work.match(/(\d{1,3}(?:\.\d{1,3}){3})$/);
+		if (!m) return null;
+		const o = m[1].split(".").map(Number);
+		if (o.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+		const hi = (o[0] << 8 | o[1]).toString(16);
+		const lo = (o[2] << 8 | o[3]).toString(16);
+		work = `${work.slice(0, work.length - m[1].length)}${hi}:${lo}`;
+	}
+	const halves = work.split("::");
+	if (halves.length > 2) return null;
+	const head = halves[0] ? halves[0].split(":") : [];
+	const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+	const groups = halves.length === 2 ? [
+		...head,
+		...Array(Math.max(0, 8 - head.length - tail.length)).fill("0"),
+		...tail
+	] : head;
+	if (groups.length !== 8) return null;
+	const hextets = groups.map((g) => /^[0-9a-f]{1,4}$/.test(g) ? Number.parseInt(g, 16) : NaN);
+	return hextets.some((n) => Number.isNaN(n)) ? null : hextets;
+}
+function isBlockedIPv6(address) {
+	const hextets = expandIPv6(address);
+	if (hextets) {
+		if (hextets.slice(0, 5).every((h) => h === 0) && (hextets[5] === 65535 || hextets[5] === 0)) {
+			const [, , , , , , g6, g7] = hextets;
+			return isBlockedIPv4(`${g6 >> 8}.${g6 & 255}.${g7 >> 8}.${g7 & 255}`);
+		}
+	}
+	const normalized = address.toLowerCase().replace(/^\[|\]$/g, "");
+	return normalized === "::" || normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || /^fe[89ab]/.test(normalized) || normalized.startsWith("ff");
+}
+function isBlockedAddress(address) {
+	const family = isIP(address);
+	if (family === 4) return isBlockedIPv4(address);
+	if (family === 6) return isBlockedIPv6(address);
+	return true;
+}
+async function assertSafeRemoteUrl(rawUrl, options = {}) {
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		throw new Error("Remote URL must be an absolute URL");
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("Remote URL must use http or https");
+	if (url.username || url.password) throw new Error("Remote URL must not include credentials");
+	if (!url.hostname) throw new Error("Remote URL must include a hostname");
+	if (options.allowPrivateNetworkHosts) return url;
+	const resolver = options.resolveHostname ?? defaultResolveHostname;
+	const addresses = isIP(url.hostname) === 0 ? await resolver(url.hostname) : [{ address: url.hostname }];
+	if (!addresses.length || addresses.some(({ address }) => isBlockedAddress(address))) throw new Error("Remote URL must resolve to a public network address");
+	return url;
+}
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+var DEFAULT_MAX_REDIRECTS = 5;
+var DEFAULT_RESOLVE_TIMEOUT_MS = 1e4;
+async function resolveSafeFinalUrl(rawUrl, options = {}) {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_RESOLVE_TIMEOUT_MS;
+	let current = await assertSafeRemoteUrl(rawUrl, options);
+	for (let hop = 0; hop <= maxRedirects; hop += 1) {
+		const response = await fetchImpl(current, {
+			method: "GET",
+			redirect: "manual",
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+		try {
+			await response.body?.cancel();
+		} catch {}
+		if (!REDIRECT_STATUSES.has(response.status)) return current;
+		const location = response.headers.get("location");
+		if (!location) return current;
+		current = await assertSafeRemoteUrl(new URL(location, current).toString(), options);
+	}
+	throw new Error("Remote URL exceeded the maximum number of redirects");
+}
+function redactUrlCredentials(raw) {
+	try {
+		const url = new URL(raw);
+		if (url.username || url.password) {
+			url.username = "";
+			url.password = "";
+			return url.toString();
+		}
+		return raw;
+	} catch {
+		return "[unparseable url]";
+	}
+}
+//#endregion
+//#region src/contents.ts
+var contents_exports = /* @__PURE__ */ __exportAll({ Contents: () => Contents });
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, {
+	enumerable: true,
+	configurable: true,
+	writable: true,
+	value
+}) : obj[key] = value;
+var __decorateClass = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp(target, key, result);
+	return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var logger = createLogger({ level: "info" });
+function isAIClientOptions(ai) {
+	return !!ai && typeof ai === "object" && !("embed" in ai) && !("generateImage" in ai);
+}
+var Contents = class extends SmrtCollection {
+	/**
+	* Configuration options
+	*/
+	options = {};
+	/**
+	* Directory to store content files
+	*/
+	contentDir;
+	/**
+	* Cache for loaded content
+	*/
+	loaded;
+	/**
+	* Creates a new Contents collection
+	*
+	* Use the static `create()` method inherited from SmrtCollection for proper initialization.
+	*
+	* @param options - Configuration options
+	*/
+	constructor(options = {}) {
+		super(options);
+		this.options = options;
+		this.loaded = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Gets the database interface
+	*
+	* @returns Database interface
+	*/
+	getDb() {
+		return this._db;
+	}
+	/**
+	* Initializes the collection
+	*
+	* @returns Promise that resolves to this instance
+	*/
+	async initialize() {
+		await super.initialize();
+		return this;
+	}
+	async getFactCollection() {
+		const { FactCollection } = await import("@happyvertical/smrt-facts");
+		return FactCollection.create(this.options);
+	}
+	/**
+	* Bounded, tenant-safe content query (`POST /api/v1/contents/query`).
+	*
+	* Accepts the canonical `DataQueryRequest` envelope (#2444) and returns a
+	* normalized `DataQueryResult`, so a list surface can filter, sort, page,
+	* count, and facet server-side instead of hydrating the whole collection.
+	*
+	* The request body carries no authority: only schema-declared field ids are
+	* accepted, and tenant scoping is applied by `executeContentQuery` itself
+	* (fail-closed to global rows when tenancy is enabled with no active tenant
+	* context). Applications that need additional site/organization scoping call
+	* `executeContentQuery` directly with a trusted `scope`.
+	*
+	* The parameter is named `options` deliberately: the route generator passes
+	* the raw request body straight through as a single `options` argument, so
+	* the wire body IS the `DataQueryRequest` rather than a wrapper object.
+	*
+	* @param options Untrusted `DataQueryRequest` from the caller.
+	* @returns A validated, bounded `DataQueryResult`.
+	*/
+	async queryAction(options) {
+		return executeContentQuery(this, options);
+	}
+	async browseFacts(options = {}) {
+		try {
+			const facts = await this.getFactCollection();
+			const query = options.query || options.q || "";
+			const limit = options.limit !== void 0 ? Number(options.limit) : void 0;
+			const offset = options.offset !== void 0 ? Number(options.offset) : void 0;
+			const minSimilarity = options.minSimilarity !== void 0 ? Number(options.minSimilarity) : void 0;
+			const includeSuperseded = options.includeSuperseded === true || options.includeSuperseded === "true";
+			const latestOnly = options.latestOnly === void 0 ? true : options.latestOnly === true || options.latestOnly === "true";
+			return (await facts.browseCatalog(query, {
+				limit: Number.isFinite(limit) ? limit : void 0,
+				offset: Number.isFinite(offset) ? offset : void 0,
+				minSimilarity: Number.isFinite(minSimilarity) ? minSimilarity : void 0,
+				includeSuperseded,
+				latestOnly,
+				tenantId: options.tenantId ?? null
+			})).map(serializeFact);
+		} catch (error) {
+			if (typeof error === "object" && error !== null && error.code === "DB_SCHEMA_MISSING") return [];
+			throw error;
+		}
+	}
+	async getBySlug(options = {}) {
+		if (!options.slug) throw new Error("slug is required");
+		const where = {
+			slug: options.slug,
+			context: options.context || ""
+		};
+		if (options.tenantId !== void 0) where.tenantId = options.tenantId;
+		const content = await this.get(where);
+		if (!content) return null;
+		if (options.status && content.status !== options.status) return null;
+		return serializeContent(content);
+	}
+	async getGovernanceDefinitionsAction(options = {}) {
+		const [effective, persisted] = await Promise.all([getEffectiveContentGovernanceConfig({
+			db: this.db,
+			tenantId: options.tenantId
+		}), loadPersistedContentGovernanceDefinitions({
+			db: this.db,
+			tenantId: options.tenantId
+		})]);
+		return {
+			effective: {
+				policies: effective.policies.map((policy) => ({
+					...policy,
+					...persisted.policies.find((item) => item.key === policy.key) || {}
+				})),
+				profiles: effective.profiles.map((profile) => ({
+					...profile,
+					...persisted.profiles.find((item) => item.key === profile.key) || {}
+				})),
+				assignments: effective.assignments.map((assignment) => ({
+					...assignment,
+					...persisted.assignments.find((item) => item.key === assignment.key) || {}
+				}))
+			},
+			persisted: {
+				policies: persisted.policies,
+				profiles: persisted.profiles,
+				assignments: persisted.assignments
+			}
+		};
+	}
+	async resolveGovernanceAction(options = {}) {
+		return resolveEffectiveContentGovernance({
+			contentType: options.type || null,
+			contentVariant: options.variant || null,
+			db: this.db,
+			tenantId: options.tenantId
+		});
+	}
+	/**
+	* Mirrors content from a remote URL
+	*
+	* Downloads and stores content from a remote URL, extracting text
+	* and saving it as a Content object.
+	*
+	* @param options - Mirror options
+	* @param options.url - URL to mirror
+	* @param options.mirrorDir - Directory for caching mirrored files
+	* @param options.context - Context for the mirrored content
+	* @returns Promise resolving to the mirrored Content object
+	* @throws Error if URL is invalid or missing
+	*/
+	async mirror(options) {
+		if (!options.url) throw new Error("No URL provided");
+		let url;
+		try {
+			url = await resolveSafeFinalUrl(options.url, {
+				allowPrivateNetworkHosts: options.allowPrivateNetworkHosts,
+				resolveHostname: options.resolveHostname,
+				fetchImpl: options.fetchImpl
+			});
+		} catch (error) {
+			const safeUrl = redactUrlCredentials(options.url);
+			logger.error("Refusing to mirror unsafe URL", {
+				error,
+				url: safeUrl
+			});
+			throw new Error(`Invalid URL provided: ${safeUrl}`);
+		}
+		const existing = await this.get({ url: options.url });
+		if (existing) return existing;
+		const doc = await fetchDocument(url.toString(), { cacheDir: options?.mirrorDir });
+		const title = (url.pathname.split("/").pop()?.replace(/\.[^/.]+$/, ""))?.replace(/[-_]/g, " ");
+		const slug = makeSlug(title);
+		const body = doc.parts.map((part) => part.content).join("\n\n");
+		if (body) {
+			const content = new Content({
+				url: options.url,
+				type: "mirror",
+				title,
+				slug,
+				context: options.context || "",
+				body
+			});
+			await content.initialize();
+			await content.save();
+			return content;
+		}
+	}
+	/**
+	* Writes a Content object to the filesystem as a markdown file
+	*
+	* @param options - Options for writing the content file
+	* @param options.content - Content object to write
+	* @param options.contentDir - Directory to write the file to
+	* @returns Promise that resolves when the file is written
+	* @throws Error if contentDir is not provided
+	*/
+	async writeContentFile(options) {
+		const { content, contentDir } = options;
+		if (!contentDir) throw new Error("No content dir provided");
+		const { body } = content;
+		const frontMatter = {
+			title: content.title,
+			slug: content.slug,
+			context: content.context,
+			author: content.author,
+			publish_date: content.publish_date
+		};
+		let output = "";
+		if (frontMatter && Object.keys(frontMatter).length > 0) {
+			output += "---\n";
+			output += YAML.stringify(frontMatter);
+			output += "---\n";
+		}
+		let formattedBody = body || "";
+		if (resolveBodyFormat(content.bodyFormat, body) === "html") formattedBody = htmlToMarkdown(body || "");
+		else if (body && !this.isMarkdown(body)) formattedBody = this.formatAsMarkdown(body);
+		output += formattedBody;
+		const pathParts = [
+			contentDir,
+			content.context || "",
+			content.slug,
+			"index.md"
+		].filter(Boolean);
+		const outputFile = path.join(...pathParts);
+		const resolvedDir = path.resolve(contentDir);
+		const resolvedFile = path.resolve(outputFile);
+		if (resolvedFile !== resolvedDir && !resolvedFile.startsWith(resolvedDir + path.sep)) throw new Error("Refusing to write content file outside of the content directory");
+		await ensureDirectoryExists(path.dirname(outputFile));
+		await writeFile(outputFile, output);
+	}
+	/**
+	* Checks if text appears to be in markdown format
+	*
+	* @param text - Text to check
+	* @returns Boolean indicating if the text contains markdown syntax
+	*/
+	isMarkdown(text) {
+		return [
+			/^#\s/m,
+			/\*\*.+\*\*/,
+			/\*.+\*/,
+			/\[.+\]\(.+\)/,
+			/^\s*[-*+]\s/m,
+			/^\s*\d+\.\s/m,
+			/```[\s\S]*```/,
+			/^\s*>/m
+		].some((indicator) => indicator.test(text));
+	}
+	/**
+	* Formats plain text as simple markdown
+	*
+	* @param text - Plain text to format
+	* @returns Text formatted as basic markdown
+	*/
+	formatAsMarkdown(text) {
+		return text.split(/\n\n+/).map((paragraph) => paragraph.trim()).filter(Boolean).join("\n\n");
+	}
+	/**
+	* Synchronizes content to the filesystem
+	*
+	* Writes all article-type Content objects to the filesystem
+	* as markdown files.
+	*
+	* @param options - Sync options
+	* @param options.contentDir - Directory to write content files to
+	* @returns Promise that resolves when synchronization is complete
+	*/
+	async syncContentDir(options) {
+		const contents = await this.list({ where: { type: "article" } });
+		for (const content of contents) await this.writeContentFile({
+			content,
+			contentDir: options.contentDir || this.options.contentDir || ""
+		});
+	}
+	/**
+	* Generate thumbnails for content that doesn't have one
+	*
+	* @param options - Options for bulk thumbnail generation
+	* @returns Promise resolving to result object with generated images and failed content IDs
+	*
+	* @example Generate headline cards for all published articles
+	* ```typescript
+	* const result = await contents.generateMissingThumbnails({
+	*   strategy: 'headline-card',
+	*   where: { type: 'article', status: 'published' },
+	*   brandColor: '#1a56db'
+	* });
+	* console.log(`Generated ${result.images.length} thumbnails`);
+	* if (result.failed.length > 0) {
+	*   console.warn(`Failed to generate ${result.failed.length} thumbnails`);
+	* }
+	* ```
+	*/
+	async generateMissingThumbnails(options) {
+		const mergedOptions = {
+			...this.options?.thumbnail || {},
+			...options
+		};
+		const whereClause = {
+			...mergedOptions.where,
+			thumbnailAssetId: null
+		};
+		const contents = await this.list({
+			where: whereClause,
+			limit: mergedOptions.limit
+		});
+		const generatedImages = [];
+		const failed = [];
+		for (const content of contents) try {
+			let thumbnailOptions;
+			switch (mergedOptions.strategy) {
+				case "headline-card":
+					thumbnailOptions = {
+						strategy: "headline-card",
+						brandColor: mergedOptions.brandColor,
+						backgroundColor: mergedOptions.backgroundColor,
+						logoUrl: mergedOptions.logoUrl,
+						template: mergedOptions.template,
+						width: mergedOptions.width,
+						height: mergedOptions.height
+					};
+					break;
+				case "static-map":
+					thumbnailOptions = {
+						strategy: "static-map",
+						mapProvider: mergedOptions.mapProvider,
+						zoom: mergedOptions.zoom,
+						width: mergedOptions.width,
+						height: mergedOptions.height
+					};
+					break;
+				case "ai-generate":
+					thumbnailOptions = {
+						strategy: "ai-generate",
+						style: mergedOptions.style,
+						width: mergedOptions.width,
+						height: mergedOptions.height,
+						ai: isAIClientOptions(this.options.ai) ? this.options.ai : void 0
+					};
+					break;
+				default: throw new Error(`Unknown strategy: ${mergedOptions.strategy}`);
+			}
+			const image = await content.generateThumbnail(thumbnailOptions);
+			generatedImages.push(image);
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			logger.error(`Failed to generate thumbnail for content ${content.id}: ${errorMessage}`);
+			failed.push({
+				contentId: content.id ?? "unknown",
+				error: errorMessage
+			});
+		}
+		return {
+			images: generatedImages,
+			failed
+		};
+	}
+	/**
+	* Find all content belonging to a specific tenant
+	*
+	* @param tenantId - The tenant ID to filter by
+	* @returns Promise resolving to array of Content objects for the tenant
+	*
+	* @example
+	* ```typescript
+	* const tenantContent = await contents.findByTenant('tenant-123');
+	* ```
+	*/
+	async findByTenant(tenantId) {
+		return this.list({ where: { tenantId } });
+	}
+	/**
+	* Find all global content (not associated with any tenant).
+	*
+	* Routes through the shared tenant-global helper so it does not throw under
+	* an active tenant context (an explicit `tenant_id IS NULL` filter would be
+	* flagged as an isolation violation). (#1600)
+	*
+	* @returns Promise resolving to array of global Content objects
+	*
+	* @example
+	* ```typescript
+	* const globalContent = await contents.findGlobal();
+	* ```
+	*/
+	async findGlobal() {
+		return queryGlobal(this);
+	}
+	/**
+	* Find content for a tenant including global content.
+	*
+	* This returns both tenant-specific content and global content (tenantId is null),
+	* useful for showing a tenant their content plus any shared/global resources.
+	*
+	* Fails closed if an active tenant context requests a different tenant's
+	* rows; the admin/system path keeps the cross-tenant capability. (#1600)
+	*
+	* @param tenantId - The tenant ID to include
+	* @returns Promise resolving to array of Content objects (tenant + global)
+	*
+	* @example
+	* ```typescript
+	* const allAccessibleContent = await contents.findWithGlobals('tenant-123');
+	* ```
+	*/
+	async findWithGlobals(tenantId) {
+		return queryWithGlobals(this, tenantId, "Content.findWithGlobals");
+	}
+};
+/**
+* Class constructor for collection items
+*/
+__publicField(Contents, "_itemClass", Content);
+Contents = __decorateClass([smrt({
+	api: {
+		include: [
+			"browseFacts",
+			"getBySlug",
+			"getGovernanceDefinitionsAction",
+			"resolveGovernanceAction",
+			"queryAction"
+		],
+		routes: {
+			queryAction: {
+				scope: "collection",
+				method: "POST",
+				path: "query"
+			},
+			browseFacts: {
+				scope: "collection",
+				method: "GET",
+				path: "facts"
+			},
+			getBySlug: {
+				scope: "collection",
+				method: "GET",
+				path: "by-slug"
+			},
+			getGovernanceDefinitionsAction: {
+				scope: "collection",
+				method: "GET",
+				path: "governance"
+			},
+			resolveGovernanceAction: {
+				scope: "collection",
+				method: "GET",
+				path: "governance/resolve"
+			}
+		}
+	},
+	mcp: false,
+	cli: false
+})], Contents);
+//#endregion
+export { contents_exports as n, assertSafeRemoteUrl as r, Contents as t };
+
+//# sourceMappingURL=contents-BrGxWH3s.js.map