@replohq/sdk 0.11.0 → 0.14.0

package/content.d.ts

@@ -0,0 +1,126 @@
+import "server-only";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import type { ContentManifest } from "./_vendor/schemas/contentManifest";
+import { contentCollectionFieldSchema } from "./_vendor/schemas/contentCollection";
+import { z } from "zod";
+/** Public name for the shared collection-field contract. */
+export type ContentField = z.infer<typeof contentCollectionFieldSchema>;
+export interface ContentEntry {
+    collection: {
+        name: string;
+        description: string;
+        slug: string;
+    };
+    fields: ContentField[];
+    slug: string;
+    body: string;
+    values: Record<string, unknown>;
+}
+/** One entry's slot in a collection listing. */
+export interface ContentCollectionEntry {
+    slug: string;
+    title: string;
+    excerpt: string | null;
+    coverImage: string | null;
+    coverImageAlt: string | null;
+    publishedAt: string | null;
+    status: "draft" | "published";
+}
+export interface ContentCollection {
+    slug: string;
+    name: string;
+    description: string;
+    entries: ContentCollectionEntry[];
+}
+/** An ordered content field paired with this entry's value for it. */
+export interface ContentFieldWithValue {
+    field: ContentField;
+    value: unknown;
+}
+export interface ContentSitemapEntry {
+    url: string;
+    lastModified?: Date;
+}
+export interface ContentSource {
+    read(relativePath: string): Promise<string | null>;
+    listCollections(): Promise<string[]>;
+    listEntries(collection: string): Promise<string[]>;
+}
+interface ContentOptions {
+    contentSource?: ContentSource;
+    contentDirectory?: string;
+    contentManifest?: ContentManifest;
+}
+export declare function createContentSource({ contentDirectory, contentManifest, }?: {
+    contentDirectory?: string;
+    contentManifest?: ContentManifest;
+}): ContentSource;
+export declare function getContentEntry({ collection, slug, ...contentOptions }: {
+    collection: string;
+    slug: string;
+} & ContentOptions): Promise<ContentEntry>;
+/** Static params for one collection's `[slug]` detail route. */
+export declare function getContentCollectionStaticParams({ collection, ...contentOptions }: {
+    collection: string;
+} & ContentOptions): Promise<{
+    slug: string;
+}[]>;
+/**
+ * A collection and its renderable entries for a listing page. Uses the
+ * not-found contract when the collection is missing or archived.
+ */
+export declare function getContentCollection({ collection, ...contentOptions }: {
+    collection: string;
+} & ContentOptions): Promise<ContentCollection>;
+/**
+ * Per-entry head metadata (title/description/OpenGraph/Twitter) from the
+ * entry's SEO fields with content fallbacks. Returns an empty object when the
+ * entry is not renderable, so `generateMetadata` can call it unconditionally.
+ */
+export declare function getContentEntryMetadata({ collection, slug, ...contentOptions }: {
+    collection: string;
+    slug: string;
+} & ContentOptions): Promise<Metadata>;
+/**
+ * Structured data for an entry as a JSON-LD script tag. Serialization is
+ * script-safe (`<` escaped) so entry content can never break out of the tag.
+ * The type is a deliberately neutral `WebPage`; collections have no schema
+ * type of their own.
+ */
+export declare function ContentEntryJsonLd({ entry }: {
+    entry: ContentEntry;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Absolute sitemap entries for every collection listing and renderable entry.
+ * `origin` comes from the caller (e.g. the request's platform-validated Host)
+ * because site origins are not fixed at build time.
+ */
+export declare function getContentSitemapEntries({ origin, ...contentOptions }: {
+    origin: string;
+} & ContentOptions): Promise<ContentSitemapEntry[]>;
+/**
+ * The full sitemap XML document for a site's content (home, collection
+ * listings, entries). Kept here so the generated sitemap route stays a tiny,
+ * restylable-free shell around one call.
+ */
+export declare function getContentSitemapXml({ origin, ...contentOptions }: {
+    origin: string;
+} & ContentOptions): Promise<string>;
+/**
+ * The entry's renderable content fields in collection-settings order, paired
+ * with values. This is the published half of the shared ordering contract in
+ * `schemas/contentCollection`; empty values are omitted so templates never render
+ * bare labels.
+ */
+export declare function getContentFields(entry: ContentEntry): ContentFieldWithValue[];
+export declare function ContentFieldValue({ field, value, }: {
+    field: ContentField;
+    value: unknown;
+}): ReactNode;
+/** A related entry resolved to a public link; unresolvable refs stay plain text. */
+export interface ContentRelatedLink {
+    title: string;
+    href: string;
+}
+export {};

package/content.js

@@ -0,0 +1,594 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import "server-only";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Fragment } from "react";
+import { notFound } from "next/navigation";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { parseJsonOrNull } from "./_vendor/replo-utils/lib/json.mjs";
+import { isNotNullish } from "./_vendor/replo-utils/lib/misc.mjs";
+import {
+  CONTENT_COLLECTION_SCHEMA_FILENAME,
+  CONTENT_DIRNAME,
+  CONTENT_ENTRY_FILE_EXTENSION,
+  CONTENT_RELATED_VALUE_STORAGE_KEY,
+  contentCollectionFileSchema,
+  getPublishedContentFields,
+  isContentEntryPubliclyVisible,
+  isSafeContentUrl,
+  isValidContentSlug,
+  parseContentEntryRef
+} from "./_vendor/schemas/contentCollection.mjs";
+import {
+  getContentEntryFieldValidationIssues,
+  getContentRenderableEntryValues,
+  parseContentEntryDocument
+} from "./_vendor/schemas/contentEntry.mjs";
+import {
+  getContentManifestCollectionSlugs,
+  getContentManifestEntrySlugs
+} from "./_vendor/schemas/contentManifest.mjs";
+import { z } from "zod";
+function createContentSource({
+  contentDirectory = getDefaultContentDirectory(),
+  contentManifest
+} = {}) {
+  if (contentManifest) {
+    return {
+      read: async (relativePath) => {
+        return contentManifest.files[relativePath] ?? null;
+      },
+      listCollections: async () => {
+        return getContentManifestCollectionSlugs(contentManifest);
+      },
+      listEntries: async (collection) => {
+        return getContentManifestEntrySlugs({ collection, contentManifest });
+      }
+    };
+  }
+  return {
+    read: (relativePath) => {
+      return readTextFileOrNull(join(contentDirectory, relativePath));
+    },
+    listCollections: async () => {
+      return (await readDirectoryOrEmpty(contentDirectory)).flatMap((entry) => {
+        return entry.isDirectory() ? [entry.name] : [];
+      });
+    },
+    listEntries: async (collection) => {
+      return (await readDirectoryOrEmpty(join(contentDirectory, collection))).flatMap((entry) => {
+        return entry.isFile() && entry.name.endsWith(CONTENT_ENTRY_FILE_EXTENSION) ? [entry.name.slice(0, -CONTENT_ENTRY_FILE_EXTENSION.length)] : [];
+      });
+    }
+  };
+}
+async function getContentEntry({
+  collection,
+  slug,
+  ...contentOptions
+}) {
+  const entry = await findContentEntry({
+    collection,
+    slug,
+    contentSource: getContentSource(contentOptions)
+  });
+  if (!entry) {
+    notFound();
+  }
+  return entry;
+}
+async function getContentCollectionStaticParams({
+  collection,
+  ...contentOptions
+}) {
+  const contentSource = getContentSource(contentOptions);
+  const collectionSchema = await readActiveCollectionSchema({
+    collection,
+    contentSource
+  });
+  if (!collectionSchema) {
+    return [];
+  }
+  const entries = await listVisibleEntries({
+    collectionSchema,
+    collection,
+    contentSource
+  });
+  return entries.map((entry) => entry.slug).sort().map((slug) => ({ slug }));
+}
+async function getContentCollection({
+  collection,
+  ...contentOptions
+}) {
+  const loaded = await findContentCollection({
+    collection,
+    contentSource: getContentSource(contentOptions)
+  });
+  if (!loaded) {
+    notFound();
+  }
+  return loaded;
+}
+async function getContentEntryMetadata({
+  collection,
+  slug,
+  ...contentOptions
+}) {
+  const entry = await findContentEntry({
+    collection,
+    slug,
+    contentSource: getContentSource(contentOptions)
+  });
+  if (!entry) {
+    return {};
+  }
+  const title = readNonEmptyString(entry.values.seoTitle) ?? readNonEmptyString(entry.values.title) ?? entry.collection.name;
+  const description = readNonEmptyString(entry.values.seoDescription) ?? readNonEmptyString(entry.values.excerpt);
+  const image = readSafeImageUrl(entry.values.coverImage);
+  return {
+    title,
+    ...description === null ? {} : { description },
+    openGraph: {
+      title,
+      ...description === null ? {} : { description },
+      type: "article",
+      ...image === null ? {} : { images: [image] }
+    },
+    twitter: {
+      card: image === null ? "summary" : "summary_large_image",
+      title,
+      ...description === null ? {} : { description },
+      ...image === null ? {} : { images: [image] }
+    }
+  };
+}
+function ContentEntryJsonLd({ entry }) {
+  const title = readNonEmptyString(entry.values.seoTitle) ?? readNonEmptyString(entry.values.title) ?? entry.collection.name;
+  const description = readNonEmptyString(entry.values.seoDescription) ?? readNonEmptyString(entry.values.excerpt);
+  const image = readSafeImageUrl(entry.values.coverImage);
+  const datePublished = readIsoDate(entry.values.publishedAt);
+  const dateModified = readIsoDate(entry.values.updatedAt);
+  const jsonLd = {
+    "@context": "https://schema.org",
+    "@type": "WebPage",
+    name: title,
+    ...description === null ? {} : { description },
+    ...image === null ? {} : { image },
+    ...datePublished === null ? {} : { datePublished },
+    ...dateModified === null ? {} : { dateModified }
+  };
+  return /* @__PURE__ */ jsx(
+    "script",
+    {
+      type: "application/ld+json",
+      dangerouslySetInnerHTML: { __html: serializeJsonLd(jsonLd) }
+    }
+  );
+}
+async function getContentSitemapEntries({
+  origin,
+  ...contentOptions
+}) {
+  const base = origin.replace(/\/+$/u, "");
+  const entries = [];
+  const contentSource = getContentSource(contentOptions);
+  for (const collection of await listCollectionSlugs({ contentSource })) {
+    const collectionSchema = await readActiveCollectionSchema({
+      collection,
+      contentSource
+    });
+    if (!collectionSchema) {
+      continue;
+    }
+    if (collectionSchema.hasListingPage !== false) {
+      entries.push({ url: `${base}/${collection}` });
+    }
+    const visibleEntries = await listVisibleEntries({
+      collectionSchema,
+      collection,
+      contentSource
+    });
+    visibleEntries.sort((left, right) => left.slug.localeCompare(right.slug));
+    for (const entry of visibleEntries) {
+      const lastModified = readValidDate(entry.values.updatedAt);
+      entries.push({
+        url: `${base}/${collection}/${entry.slug}`,
+        ...lastModified === null ? {} : { lastModified }
+      });
+    }
+  }
+  return entries;
+}
+async function getContentSitemapXml({
+  origin,
+  ...contentOptions
+}) {
+  const base = origin.replace(/\/+$/u, "");
+  const entries = [
+    { url: base },
+    ...await getContentSitemapEntries({
+      origin: base,
+      contentSource: getContentSource(contentOptions)
+    })
+  ];
+  const items = entries.map(({ url, lastModified }) => {
+    const lastmod = lastModified ? `<lastmod>${lastModified.toISOString()}</lastmod>` : "";
+    return `<url><loc>${escapeXml(url)}</loc>${lastmod}</url>`;
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${items.join(
+    ""
+  )}</urlset>
+`;
+}
+function getContentFields(entry) {
+  return getPublishedContentFields(entry.fields).map((field) => ({ field, value: entry.values[field.id] })).filter(({ value }) => {
+    return value !== void 0 && value !== null && value !== "";
+  });
+}
+function ContentFieldValue({
+  field,
+  value
+}) {
+  if (field.type === "rich-text" && typeof value === "string") {
+    return /* @__PURE__ */ jsx(SafeMarkdown, { source: value });
+  }
+  if (field.type === "image" && typeof value === "string") {
+    return /* @__PURE__ */ jsx(
+      "img",
+      {
+        alt: field.label,
+        src: value,
+        style: { display: "block", height: "auto", maxWidth: "100%" }
+      }
+    );
+  }
+  if (field.type === "url" && typeof value === "string") {
+    return /* @__PURE__ */ jsx("a", { href: value, style: CONTENT_LINK_STYLE, children: value });
+  }
+  if (field.type === "date" && typeof value === "string") {
+    const parsed = new Date(value);
+    const label = Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "long",
+      day: "numeric"
+    });
+    return /* @__PURE__ */ jsx("time", { dateTime: value, children: label });
+  }
+  if (field.type === "boolean" && typeof value === "boolean") {
+    return value ? "Yes" : "No";
+  }
+  if (field.type === "related" && Array.isArray(value)) {
+    const items = value.filter(
+      (item) => isContentRelatedLink(item) || typeof item === "string"
+    );
+    if (items.length === 0) {
+      return null;
+    }
+    return items.map((item, index) => /* @__PURE__ */ jsxs(Fragment, { children: [
+      index > 0 && ", ",
+      isContentRelatedLink(item) ? /* @__PURE__ */ jsx("a", { href: item.href, style: CONTENT_LINK_STYLE, children: item.title }) : String(item)
+    ] }, isContentRelatedLink(item) ? item.href : String(item)));
+  }
+  if (field.type === "tags" && Array.isArray(value)) {
+    return value.join(", ");
+  }
+  return typeof value === "string" ? value : null;
+}
+async function findContentCollection({
+  collection,
+  contentSource
+}) {
+  const collectionSchema = await readActiveCollectionSchema({
+    collection,
+    contentSource
+  });
+  if (!collectionSchema) {
+    return null;
+  }
+  const visibleEntries = await listVisibleEntries({
+    collectionSchema,
+    collection,
+    contentSource
+  });
+  const entries = visibleEntries.map((entry) => {
+    return {
+      slug: entry.slug,
+      title: readNonEmptyString(entry.values.title) ?? entry.slug,
+      excerpt: readNonEmptyString(entry.values.excerpt),
+      coverImage: readSafeImageUrl(entry.values.coverImage),
+      coverImageAlt: readNonEmptyString(entry.values.coverImageAlt),
+      publishedAt: readIsoDate(entry.values.publishedAt),
+      status: entry.values.status === "draft" ? "draft" : "published"
+    };
+  });
+  entries.sort((left, right) => {
+    const leftTime = left.publishedAt ? Date.parse(left.publishedAt) : 0;
+    const rightTime = right.publishedAt ? Date.parse(right.publishedAt) : 0;
+    return rightTime - leftTime || left.title.localeCompare(right.title);
+  });
+  return {
+    slug: collection,
+    name: collectionSchema.name,
+    description: collectionSchema.description,
+    entries
+  };
+}
+async function findContentEntry({
+  collection,
+  slug,
+  contentSource
+}) {
+  const collectionSchema = await readActiveCollectionSchema({
+    collection,
+    contentSource
+  });
+  if (!collectionSchema) {
+    return null;
+  }
+  return readVisibleEntry({
+    collectionSchema,
+    collection,
+    slug,
+    contentSource
+  });
+}
+async function listCollectionSlugs({
+  contentSource
+}) {
+  return (await contentSource.listCollections()).filter(isValidContentSlug).sort();
+}
+async function listVisibleEntries({
+  collectionSchema,
+  collection,
+  contentSource
+}) {
+  const slugs = await contentSource.listEntries(collection);
+  const entries = await Promise.all(
+    slugs.map((slug) => {
+      return readVisibleEntry({
+        collectionSchema,
+        collection,
+        slug,
+        contentSource
+      });
+    })
+  );
+  return entries.filter(isNotNullish);
+}
+async function readActiveCollectionSchema({
+  collection,
+  contentSource
+}) {
+  if (!isValidContentSlug(collection)) {
+    return null;
+  }
+  const rawSchema = await contentSource.read(
+    `${collection}/${CONTENT_COLLECTION_SCHEMA_FILENAME}`
+  );
+  if (!rawSchema) {
+    return null;
+  }
+  const parsedJson = parseJsonOrNull(rawSchema);
+  if (parsedJson === null) {
+    return null;
+  }
+  const result = contentCollectionFileSchema.safeParse(parsedJson);
+  if (!result.success || isNotNullish(result.data.archivedAt)) {
+    return null;
+  }
+  return result.data;
+}
+async function readVisibleEntryDocument({
+  collection,
+  slug,
+  contentSource
+}) {
+  if (!isValidContentSlug(slug)) {
+    return null;
+  }
+  const rawEntry = await contentSource.read(
+    `${collection}/${slug}${CONTENT_ENTRY_FILE_EXTENSION}`
+  );
+  if (!rawEntry) {
+    return null;
+  }
+  const parsedDocument = parseContentEntryDocument(rawEntry);
+  if (parsedDocument.status === "invalid") {
+    return null;
+  }
+  const document = parsedDocument.document;
+  const allowDrafts = process.env.NODE_ENV === "development";
+  if (!isContentEntryPubliclyVisible({
+    status: document.values.status,
+    archivedAt: document.values.archivedAt,
+    allowDrafts
+  })) {
+    return null;
+  }
+  return document;
+}
+async function readVisibleEntry({
+  collectionSchema,
+  collection,
+  slug,
+  contentSource
+}) {
+  const document = await readVisibleEntryDocument({
+    collection,
+    slug,
+    contentSource
+  });
+  if (!document) {
+    return null;
+  }
+  const values = getContentRenderableEntryValues({
+    document,
+    slug
+  });
+  if (getContentEntryFieldValidationIssues({
+    fields: collectionSchema.fields,
+    values,
+    requireRequiredFields: document.values.status !== "draft"
+  }).length > 0) {
+    return null;
+  }
+  const fields = [...collectionSchema.fields];
+  const hasRelatedField = fields.some((field) => field.type === "related");
+  const storedRelated = values[CONTENT_RELATED_VALUE_STORAGE_KEY];
+  if (!hasRelatedField && Array.isArray(storedRelated) && storedRelated.length > 0) {
+    fields.push({
+      id: CONTENT_RELATED_VALUE_STORAGE_KEY,
+      label: "Related content",
+      type: "related",
+      required: false,
+      enabled: true,
+      builtin: true
+    });
+  }
+  return {
+    collection: {
+      name: collectionSchema.name,
+      description: collectionSchema.description,
+      slug: collection
+    },
+    fields,
+    slug,
+    body: document.body,
+    values: await resolveRelatedFieldValues({
+      fields,
+      values,
+      contentSource
+    })
+  };
+}
+async function resolveRelatedFieldValues({
+  fields,
+  values,
+  contentSource
+}) {
+  const relatedFields = fields.filter((field) => field.type === "related");
+  if (relatedFields.length === 0) {
+    return values;
+  }
+  const resolved = { ...values };
+  for (const field of relatedFields) {
+    const raw = resolved[field.id];
+    if (!Array.isArray(raw)) {
+      continue;
+    }
+    const links = [];
+    for (const item of raw) {
+      if (typeof item !== "string") {
+        continue;
+      }
+      const ref = parseContentEntryRef(item);
+      if (!ref) {
+        continue;
+      }
+      const { collectionSlug: targetCollection, entrySlug: targetSlug } = ref;
+      const collectionSchema = await readActiveCollectionSchema({
+        collection: targetCollection,
+        contentSource
+      });
+      if (!collectionSchema) {
+        continue;
+      }
+      const target = await readVisibleEntryDocument({
+        collection: targetCollection,
+        slug: targetSlug,
+        contentSource
+      });
+      if (!target) {
+        continue;
+      }
+      links.push({
+        title: readNonEmptyString(target.values.title) ?? targetSlug,
+        href: `/${targetCollection}/${targetSlug}`
+      });
+    }
+    resolved[field.id] = links;
+  }
+  return resolved;
+}
+const contentRelatedLinkSchema = z.object({
+  title: z.string(),
+  href: z.string()
+});
+function isContentRelatedLink(value) {
+  return contentRelatedLinkSchema.safeParse(value).success;
+}
+const CONTENT_LINK_STYLE = { textDecoration: "underline" };
+function SafeMarkdown({ source }) {
+  return /* @__PURE__ */ jsx(
+    ReactMarkdown,
+    {
+      remarkPlugins: [remarkGfm],
+      skipHtml: true,
+      components: {
+        a: ({ children, ...props }) => /* @__PURE__ */ jsx("a", { ...props, style: CONTENT_LINK_STYLE, children })
+      },
+      children: source
+    }
+  );
+}
+function readNonEmptyString(value) {
+  const parsed = z.string().safeParse(value);
+  return parsed.success && parsed.data.trim().length > 0 ? parsed.data : null;
+}
+function readSafeImageUrl(value) {
+  const url = readNonEmptyString(value);
+  return url !== null && isSafeContentUrl(url, { image: true }) ? url : null;
+}
+function readIsoDate(value) {
+  const raw = readNonEmptyString(value);
+  return raw !== null && !Number.isNaN(Date.parse(raw)) ? raw : null;
+}
+function readValidDate(value) {
+  const iso = readIsoDate(value);
+  return iso === null ? null : new Date(iso);
+}
+function serializeJsonLd(value) {
+  return JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+}
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+async function readTextFileOrNull(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function readDirectoryOrEmpty(path) {
+  try {
+    return await readdir(path, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+function getContentSource({
+  contentSource,
+  contentDirectory,
+  contentManifest
+}) {
+  return contentSource ?? createContentSource({ contentDirectory, contentManifest });
+}
+function getDefaultContentDirectory() {
+  return join(process.cwd(), CONTENT_DIRNAME);
+}
+export {
+  ContentEntryJsonLd,
+  ContentFieldValue,
+  createContentSource,
+  getContentCollection,
+  getContentCollectionStaticParams,
+  getContentEntry,
+  getContentEntryMetadata,
+  getContentFields,
+  getContentSitemapEntries,
+  getContentSitemapXml
+};
+//# sourceMappingURL=content.js.map