@asteroidcms/core-utils 0.1.7 → 0.2.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient, DocumentNode } from '@apollo/client';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type AsteroidCMSConfig = {
     /** Base URL of the Asteroid CMS API (e.g. https://cms-api.example.com). */
@@ -227,4 +228,188 @@ declare function extractHeadingsFromElement(root: HTMLElement, options?: Extract
     scrollMarginTop?: number;
 }): ExtractedHeading[];
 
-export { type AsteroidCMSConfig, type CmsMutateOptions, type CmsSearchCondition, type ContentStatus, type ExtractHeadingsOptions, type ExtractedHeading, type FieldSelector$1 as FieldSelector, type HeadingLevel, type MutationType, type ParseRichTextOptions, type ReferenceExpansion$1 as ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type UseCmsContentOptions, buildCmsMutation, buildCmsQuery, cmsImage, cmsMutate, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, slugify };
+interface ISeoValues {
+    title: string;
+    siteName: string;
+    twitter: string;
+    description: string;
+    url: string;
+    keywords: string;
+    image?: string;
+    noindex?: boolean;
+    manifestUrl?: string;
+}
+type SeoClientProps = {
+    title: string;
+    description: string;
+    url: string;
+    siteName?: string;
+    keywords?: string;
+    twitter?: string;
+    image?: string;
+    noindex?: boolean;
+};
+/** Theme colors used when generating dynamic OG images. */
+interface AsteroidOgImagePalette {
+    background: string;
+    foreground: string;
+    accent: string;
+    accentMuted?: string;
+    mutedText?: string;
+}
+interface AsteroidOgImageParams {
+    title: string;
+    subtitle?: string;
+    eyebrow?: string;
+    type?: "article" | "listing";
+}
+/** Options for the generic per-page SEO builder (landing pages, etc.). */
+interface AsteroidPageSeoOptions {
+    /** Raw page title; the config `titleTemplate` (or the `| siteName` default) is applied. */
+    title: string;
+    description?: string;
+    /** Path appended to `baseUrl`. Default: `/`. */
+    path?: string;
+    keywords?: string;
+    /** Explicit social image URL. If absent, a generated OG image is used. */
+    image?: string;
+    /** Eyebrow label for the generated OG image. */
+    eyebrow?: string;
+    /** Open Graph object type. Default: `website`. */
+    ogType?: "website" | "article";
+    /** Mark the page as `noindex` for search engines. */
+    noindex?: boolean;
+}
+/** Site-level identity used to build the Organization/WebSite JSON-LD graph. */
+interface AsteroidOrganizationConfig {
+    logoUrl?: string;
+    contactEmail?: string;
+    contactPhone?: string;
+    address?: {
+        street?: string;
+        city?: string;
+        country?: string;
+    };
+    /** Generic list of profile URLs (LinkedIn, X, etc.). Maps to schema.org `sameAs`. */
+    socials?: string[];
+}
+/** Site-level SEO config passed into the headless Asteroid content components. */
+interface AsteroidSeoConfig {
+    siteName: string;
+    baseUrl: string;
+    twitter?: string;
+    defaultDescription?: string;
+    defaultKeywords?: string;
+    /** Path prefix for the article collection (e.g. `/blog`, `/news`, `/docs`). Default: `/blog` */
+    articlePath?: string;
+    /**
+     * Human label for the article collection, used in default titles/eyebrows
+     * (e.g. "Blog", "News", "Documentation"). Default: `"Articles"`.
+     */
+    contentLabel?: string;
+    /**
+     * Override how a raw page/article title becomes the final `<title>`.
+     * Default: `(title) => `${title} | ${siteName}``.
+     */
+    titleTemplate?: (title: string) => string;
+    ogImage?: {
+        palette: AsteroidOgImagePalette;
+        /** OG image API route path. Default: `/api/og` */
+        apiPath?: string;
+    };
+    /** Override dynamic OG image URL generation (e.g. custom CDN or renderer). */
+    getOgImageUrl?: (params: AsteroidOgImageParams) => string | undefined;
+    /** Site identity for the Organization/WebSite JSON-LD graph. */
+    organization?: AsteroidOrganizationConfig;
+    /** Extra schema.org @graph nodes (e.g. a ProfessionalService node). */
+    extraJsonLdNodes?: object[];
+    /** CMS base URL for resolving featured-image URLs. Required server-side for featured images. */
+    cmsUrl?: string;
+    /** URL to a PWA manifest.json. When set, a `<link rel="manifest">` is emitted. */
+    manifestUrl?: string;
+    /** Site-wide default robots policy. Per-page overrides are available on builder options. */
+    noindex?: boolean;
+}
+
+/** Apply the configured title template, defaulting to `${title} | ${siteName}`. */
+declare function applyTitleTemplate(config: AsteroidSeoConfig, title: string): string;
+declare function buildOgImageUrl(config: AsteroidSeoConfig, params: AsteroidOgImageParams): string | undefined;
+type ArticleLike = {
+    title: string;
+    description?: string;
+    meta_description?: string;
+    featured_image?: string;
+};
+/**
+ * Generic per-page SEO builder. Use it directly for landing/marketing pages, or
+ * as the base for the article/listing wrappers below. Content-type agnostic.
+ */
+declare function buildPageSeoValues(config: AsteroidSeoConfig, options: AsteroidPageSeoOptions): ISeoValues;
+/** SEO for a single article; works for news, articles, or docs pages. */
+declare function buildArticleSeoValues<TPost extends ArticleLike>(post: TPost, config: AsteroidSeoConfig, slug: string, options?: {
+    noindex?: boolean;
+}): ISeoValues;
+/** SEO for an article collection / category listing (any content type). */
+declare function buildArticleListingSeoValues(config: AsteroidSeoConfig, options?: {
+    categoryName?: string;
+    categorySlug?: string;
+    noindex?: boolean;
+}): ISeoValues;
+declare function seoValuesToClientProps(values: ISeoValues): SeoClientProps;
+
+/** Build the site-wide Organization + WebSite @graph from config. */
+declare function buildSiteJsonLd(config: AsteroidSeoConfig): object;
+/** schema.org Article subtypes; pick per content kind. */
+type ArticleJsonLdType = "Article" | "BlogPosting" | "NewsArticle" | "TechArticle" | (string & {});
+type ArticleJsonLdProps = {
+    title: string;
+    description: string;
+    url: string;
+    /** Site name; used as the author fallback. */
+    siteName: string;
+    /** Normalized base URL (no trailing slash); used to reference the org/website @ids. */
+    siteUrl: string;
+    /** schema.org @type. Default: `"Article"`. */
+    articleType?: ArticleJsonLdType;
+    image?: string;
+    authorName?: string;
+    publishedTime?: string;
+    tags?: string[];
+    category?: string;
+};
+declare function buildArticleJsonLd(props: ArticleJsonLdProps): object;
+type CollectionJsonLdProps = {
+    name: string;
+    description: string;
+    url: string;
+    /** Normalized base URL (no trailing slash); used to reference the org/website @ids. */
+    siteUrl: string;
+};
+declare function buildCollectionJsonLd(props: CollectionJsonLdProps): object;
+type WebPageJsonLdProps = {
+    name: string;
+    description: string;
+    url: string;
+    /** Normalized base URL (no trailing slash); used to reference the org/website @ids. */
+    siteUrl: string;
+};
+/** Generic WebPage node for landing/marketing pages with no article concept. */
+declare function buildWebPageJsonLd(props: WebPageJsonLdProps): object;
+
+type OgImageVariant = "article" | "listing";
+interface OgImageContentParams {
+    title: string;
+    subtitle?: string;
+    eyebrow?: string;
+    siteName?: string;
+    palette: AsteroidOgImagePalette;
+    variant?: OgImageVariant;
+}
+interface ParsedOgImageParams extends OgImageContentParams {
+    variant: OgImageVariant;
+}
+declare function parseOgImageSearchParams(searchParams: URLSearchParams): ParsedOgImageParams;
+/** JSX layout consumed by `next/og` ImageResponse and compatible OG endpoints. */
+declare function OgImageContent({ title, subtitle, eyebrow, siteName, palette, variant, }: OgImageContentParams): react_jsx_runtime.JSX.Element;
+
+export { type ArticleJsonLdProps, type ArticleJsonLdType, type AsteroidCMSConfig, type AsteroidOgImagePalette, type AsteroidOgImageParams, type AsteroidOrganizationConfig, type AsteroidPageSeoOptions, type AsteroidSeoConfig, type CmsMutateOptions, type CmsSearchCondition, type CollectionJsonLdProps, type ContentStatus, type ExtractHeadingsOptions, type ExtractedHeading, type FieldSelector$1 as FieldSelector, type HeadingLevel, type ISeoValues, type MutationType, OgImageContent, type OgImageContentParams, type OgImageVariant, type ParseRichTextOptions, type ParsedOgImageParams, type ReferenceExpansion$1 as ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type SeoClientProps, type UseCmsContentOptions, type WebPageJsonLdProps, applyTitleTemplate, buildArticleJsonLd, buildArticleListingSeoValues, buildArticleSeoValues, buildCmsMutation, buildCmsQuery, buildCollectionJsonLd, buildOgImageUrl, buildPageSeoValues, buildSiteJsonLd, buildWebPageJsonLd, cmsImage, cmsMutate, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseOgImageSearchParams, parseRichText, removeEmptyParagraphs, seoValuesToClientProps, slugify };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient, DocumentNode } from '@apollo/client';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type AsteroidCMSConfig = {
     /** Base URL of the Asteroid CMS API (e.g. https://cms-api.example.com). */
@@ -227,4 +228,188 @@ declare function extractHeadingsFromElement(root: HTMLElement, options?: Extract
     scrollMarginTop?: number;
 }): ExtractedHeading[];
 
-export { type AsteroidCMSConfig, type CmsMutateOptions, type CmsSearchCondition, type ContentStatus, type ExtractHeadingsOptions, type ExtractedHeading, type FieldSelector$1 as FieldSelector, type HeadingLevel, type MutationType, type ParseRichTextOptions, type ReferenceExpansion$1 as ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type UseCmsContentOptions, buildCmsMutation, buildCmsQuery, cmsImage, cmsMutate, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, slugify };
+interface ISeoValues {
+    title: string;
+    siteName: string;
+    twitter: string;
+    description: string;
+    url: string;
+    keywords: string;
+    image?: string;
+    noindex?: boolean;
+    manifestUrl?: string;
+}
+type SeoClientProps = {
+    title: string;
+    description: string;
+    url: string;
+    siteName?: string;
+    keywords?: string;
+    twitter?: string;
+    image?: string;
+    noindex?: boolean;
+};
+/** Theme colors used when generating dynamic OG images. */
+interface AsteroidOgImagePalette {
+    background: string;
+    foreground: string;
+    accent: string;
+    accentMuted?: string;
+    mutedText?: string;
+}
+interface AsteroidOgImageParams {
+    title: string;
+    subtitle?: string;
+    eyebrow?: string;
+    type?: "article" | "listing";
+}
+/** Options for the generic per-page SEO builder (landing pages, etc.). */
+interface AsteroidPageSeoOptions {
+    /** Raw page title; the config `titleTemplate` (or the `| siteName` default) is applied. */
+    title: string;
+    description?: string;
+    /** Path appended to `baseUrl`. Default: `/`. */
+    path?: string;
+    keywords?: string;
+    /** Explicit social image URL. If absent, a generated OG image is used. */
+    image?: string;
+    /** Eyebrow label for the generated OG image. */
+    eyebrow?: string;
+    /** Open Graph object type. Default: `website`. */
+    ogType?: "website" | "article";
+    /** Mark the page as `noindex` for search engines. */
+    noindex?: boolean;
+}
+/** Site-level identity used to build the Organization/WebSite JSON-LD graph. */
+interface AsteroidOrganizationConfig {
+    logoUrl?: string;
+    contactEmail?: string;
+    contactPhone?: string;
+    address?: {
+        street?: string;
+        city?: string;
+        country?: string;
+    };
+    /** Generic list of profile URLs (LinkedIn, X, etc.). Maps to schema.org `sameAs`. */
+    socials?: string[];
+}
+/** Site-level SEO config passed into the headless Asteroid content components. */
+interface AsteroidSeoConfig {
+    siteName: string;
+    baseUrl: string;
+    twitter?: string;
+    defaultDescription?: string;
+    defaultKeywords?: string;
+    /** Path prefix for the article collection (e.g. `/blog`, `/news`, `/docs`). Default: `/blog` */
+    articlePath?: string;
+    /**
+     * Human label for the article collection, used in default titles/eyebrows
+     * (e.g. "Blog", "News", "Documentation"). Default: `"Articles"`.
+     */
+    contentLabel?: string;
+    /**
+     * Override how a raw page/article title becomes the final `<title>`.
+     * Default: `(title) => `${title} | ${siteName}``.
+     */
+    titleTemplate?: (title: string) => string;
+    ogImage?: {
+        palette: AsteroidOgImagePalette;
+        /** OG image API route path. Default: `/api/og` */
+        apiPath?: string;
+    };
+    /** Override dynamic OG image URL generation (e.g. custom CDN or renderer). */
+    getOgImageUrl?: (params: AsteroidOgImageParams) => string | undefined;
+    /** Site identity for the Organization/WebSite JSON-LD graph. */
+    organization?: AsteroidOrganizationConfig;
+    /** Extra schema.org @graph nodes (e.g. a ProfessionalService node). */
+    extraJsonLdNodes?: object[];
+    /** CMS base URL for resolving featured-image URLs. Required server-side for featured images. */
+    cmsUrl?: string;
+    /** URL to a PWA manifest.json. When set, a `<link rel="manifest">` is emitted. */
+    manifestUrl?: string;
+    /** Site-wide default robots policy. Per-page overrides are available on builder options. */
+    noindex?: boolean;
+}
+
+/** Apply the configured title template, defaulting to `${title} | ${siteName}`. */
+declare function applyTitleTemplate(config: AsteroidSeoConfig, title: string): string;
+declare function buildOgImageUrl(config: AsteroidSeoConfig, params: AsteroidOgImageParams): string | undefined;
+type ArticleLike = {
+    title: string;
+    description?: string;
+    meta_description?: string;
+    featured_image?: string;
+};
+/**
+ * Generic per-page SEO builder. Use it directly for landing/marketing pages, or
+ * as the base for the article/listing wrappers below. Content-type agnostic.
+ */
+declare function buildPageSeoValues(config: AsteroidSeoConfig, options: AsteroidPageSeoOptions): ISeoValues;
+/** SEO for a single article; works for news, articles, or docs pages. */
+declare function buildArticleSeoValues<TPost extends ArticleLike>(post: TPost, config: AsteroidSeoConfig, slug: string, options?: {
+    noindex?: boolean;
+}): ISeoValues;
+/** SEO for an article collection / category listing (any content type). */
+declare function buildArticleListingSeoValues(config: AsteroidSeoConfig, options?: {
+    categoryName?: string;
+    categorySlug?: string;
+    noindex?: boolean;
+}): ISeoValues;
+declare function seoValuesToClientProps(values: ISeoValues): SeoClientProps;
+
+/** Build the site-wide Organization + WebSite @graph from config. */
+declare function buildSiteJsonLd(config: AsteroidSeoConfig): object;
+/** schema.org Article subtypes; pick per content kind. */
+type ArticleJsonLdType = "Article" | "BlogPosting" | "NewsArticle" | "TechArticle" | (string & {});
+type ArticleJsonLdProps = {
+    title: string;
+    description: string;
+    url: string;
+    /** Site name; used as the author fallback. */
+    siteName: string;
+    /** Normalized base URL (no trailing slash); used to reference the org/website @ids. */
+    siteUrl: string;
+    /** schema.org @type. Default: `"Article"`. */
+    articleType?: ArticleJsonLdType;
+    image?: string;
+    authorName?: string;
+    publishedTime?: string;
+    tags?: string[];
+    category?: string;
+};
+declare function buildArticleJsonLd(props: ArticleJsonLdProps): object;
+type CollectionJsonLdProps = {
+    name: string;
+    description: string;
+    url: string;
+    /** Normalized base URL (no trailing slash); used to reference the org/website @ids. */
+    siteUrl: string;
+};
+declare function buildCollectionJsonLd(props: CollectionJsonLdProps): object;
+type WebPageJsonLdProps = {
+    name: string;
+    description: string;
+    url: string;
+    /** Normalized base URL (no trailing slash); used to reference the org/website @ids. */
+    siteUrl: string;
+};
+/** Generic WebPage node for landing/marketing pages with no article concept. */
+declare function buildWebPageJsonLd(props: WebPageJsonLdProps): object;
+
+type OgImageVariant = "article" | "listing";
+interface OgImageContentParams {
+    title: string;
+    subtitle?: string;
+    eyebrow?: string;
+    siteName?: string;
+    palette: AsteroidOgImagePalette;
+    variant?: OgImageVariant;
+}
+interface ParsedOgImageParams extends OgImageContentParams {
+    variant: OgImageVariant;
+}
+declare function parseOgImageSearchParams(searchParams: URLSearchParams): ParsedOgImageParams;
+/** JSX layout consumed by `next/og` ImageResponse and compatible OG endpoints. */
+declare function OgImageContent({ title, subtitle, eyebrow, siteName, palette, variant, }: OgImageContentParams): react_jsx_runtime.JSX.Element;
+
+export { type ArticleJsonLdProps, type ArticleJsonLdType, type AsteroidCMSConfig, type AsteroidOgImagePalette, type AsteroidOgImageParams, type AsteroidOrganizationConfig, type AsteroidPageSeoOptions, type AsteroidSeoConfig, type CmsMutateOptions, type CmsSearchCondition, type CollectionJsonLdProps, type ContentStatus, type ExtractHeadingsOptions, type ExtractedHeading, type FieldSelector$1 as FieldSelector, type HeadingLevel, type ISeoValues, type MutationType, OgImageContent, type OgImageContentParams, type OgImageVariant, type ParseRichTextOptions, type ParsedOgImageParams, type ReferenceExpansion$1 as ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type SeoClientProps, type UseCmsContentOptions, type WebPageJsonLdProps, applyTitleTemplate, buildArticleJsonLd, buildArticleListingSeoValues, buildArticleSeoValues, buildCmsMutation, buildCmsQuery, buildCollectionJsonLd, buildOgImageUrl, buildPageSeoValues, buildSiteJsonLd, buildWebPageJsonLd, cmsImage, cmsMutate, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseOgImageSearchParams, parseRichText, removeEmptyParagraphs, seoValuesToClientProps, slugify };