@asteroidcms/core-utils 0.1.8 → 0.2.1

package/dist/server.d.ts

@@ -0,0 +1,342 @@
+import { ApolloClient } from '@apollo/client';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ArticleSearchBoxProps } from '@asteroidcms/core-utils/client';
+import { Metadata } from 'next';
+
+interface CmsServerClientConfig {
+    cmsUrl: string;
+    apiKey: string;
+    graphqlPath?: string;
+    headers?: Record<string, string>;
+    /** Next.js ISR revalidate seconds, applied to the GraphQL fetch. */
+    revalidate?: number;
+    /** Next.js cache tags for on-demand revalidation. */
+    tags?: string[];
+    /** Escape hatch: provide a pre-built client (e.g. registerApolloClient). */
+    getClient?: () => ApolloClient;
+}
+interface CmsServerClient {
+    getClient: () => ApolloClient;
+    cmsUrl: string;
+}
+/**
+ * Build a server-only CMS client for use with `fetchCmsContent` / `cmsMutate`.
+ * The API key stays on the server. The client is memoized per-request via
+ * React `cache()` for query deduplication.
+ */
+declare function createCmsServerClient(config: CmsServerClientConfig): CmsServerClient;
+
+type FieldSelector = string | {
+    field: string;
+    as?: string;
+};
+type ReferenceExpansion = {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+};
+type ContentStatus = "DRAFT" | "PUBLISHED" | "ARCHIVED";
+type CmsSearchCondition = {
+    field: string;
+    value: string;
+    mode?: string;
+};
+type UseCmsContentOptions = {
+    schema_slug: string;
+    entrySlug?: string;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+    fullData?: boolean;
+    limit?: number;
+    offset?: number;
+    status?: ContentStatus;
+    filter?: Record<string, string | number | boolean | null>;
+    search?: CmsSearchCondition[];
+    variables?: Record<string, unknown>;
+};
+
+/** 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";
+}
+/** 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;
+}
+
+/** schema.org Article subtypes; pick per content kind. */
+type ArticleJsonLdType = "Article" | "BlogPosting" | "NewsArticle" | "TechArticle" | (string & {});
+
+/** Resolves a CMS asset id (or passthrough URL) to an absolute media URL. */
+type ArticleImageResolver = (idOrUrl?: string) => string;
+/** Minimal article post shape shared across Asteroid CMS apps. */
+interface AsteroidArticlePost {
+    slug: string;
+    title: string;
+    description?: string;
+    featured_image?: string;
+    featured?: boolean;
+    published_date?: string | null;
+    category?: {
+        slug: string;
+        name: string;
+        description?: string;
+    };
+}
+interface AsteroidArticleCategoryGroup<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    categoryName: string;
+    categorySlug: string;
+    posts: TPost[];
+}
+/** Runtime-agnostic computed state shared by client + server listing. */
+interface ArticlesViewState<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    posts: TPost[];
+    featured: TPost | null;
+    rest: TPost[];
+    categoryGroups: AsteroidArticleCategoryGroup<TPost>[];
+    isEmpty: boolean;
+    isSearching: boolean;
+    /** The effective (already-debounced, for client) search query. */
+    searchQuery: string;
+}
+type AsteroidArticlesEmptyReason = "error" | "no-posts" | "no-results";
+interface AsteroidArticlesSearchParams {
+    value: string;
+    onChange: (value: string) => void;
+    onSubmit: (event: {
+        preventDefault: () => void;
+    }) => void;
+}
+interface AsteroidArticlesHeaderParams {
+    eyebrow: ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    search: ReactNode;
+}
+interface AsteroidArticlesFeaturedCardParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    post: TPost;
+    cmsImage: ArticleImageResolver;
+}
+interface AsteroidArticlesPostCardParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    post: TPost;
+    index: number;
+    group: AsteroidArticleCategoryGroup<TPost>;
+    cmsImage: ArticleImageResolver;
+}
+interface AsteroidArticlesPostGridParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    posts: TPost[];
+    group: AsteroidArticleCategoryGroup<TPost>;
+    children: ReactNode;
+}
+interface AsteroidArticlesCategoryHeadingParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    group: AsteroidArticleCategoryGroup<TPost>;
+}
+interface AsteroidArticlesCategoryGroupParams<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    group: AsteroidArticleCategoryGroup<TPost>;
+    defaultContent: ReactNode;
+}
+interface AsteroidArticlesEmptyParams {
+    reason: AsteroidArticlesEmptyReason;
+    searchQuery?: string;
+    error?: unknown;
+}
+interface AsteroidArticlesContentParams {
+    featured: ReactNode;
+    groups: ReactNode;
+    noSearchResults: ReactNode;
+}
+
+interface AsteroidArticlePagePost {
+    slug: string;
+    title: string;
+    description?: string;
+    content?: string;
+    featured_image?: string;
+    tags?: string;
+    published_date?: string | null;
+    category?: {
+        slug: string;
+        name: string;
+    };
+    author?: {
+        name: string;
+        bio?: string;
+    };
+}
+type Slot<TPost> = (params: {
+    post: TPost;
+    cmsImage: ArticleImageResolver;
+}) => ReactNode;
+interface ArticleBodyRenderProps<TPost extends AsteroidArticlePagePost = AsteroidArticlePagePost> {
+    backLink?: ReactNode;
+    renderHeader?: Slot<TPost>;
+    renderMeta?: Slot<TPost>;
+    renderDescription?: Slot<TPost>;
+    renderFeaturedImage?: Slot<TPost>;
+    renderToc?: Slot<TPost>;
+    renderContent?: Slot<TPost>;
+    renderPreArticle?: Slot<TPost>;
+    renderMidArticle?: Slot<TPost>;
+    renderPostArticle?: Slot<TPost>;
+    renderTags?: Slot<TPost>;
+    renderAuthorDetails?: Slot<TPost>;
+    renderRelatedPosts?: (params: {
+        post: TPost;
+        relatedPosts: TPost[];
+        cmsImage: ArticleImageResolver;
+    }) => ReactNode;
+    renderCTA?: Slot<TPost>;
+}
+
+type Select = NonNullable<UseCmsContentOptions["select"]>;
+interface ArticleSourceConfig<TPost extends AsteroidArticlePost = AsteroidArticlePost, TDetail extends AsteroidArticlePagePost = AsteroidArticlePagePost> {
+    client: CmsServerClient;
+    schemaSlug: string;
+    listSelect: Select;
+    detailSelect: Select;
+    seo: AsteroidSeoConfig;
+    searchFields?: string[];
+    status?: ContentStatus;
+    articleType?: ArticleJsonLdType;
+    relatedLimit?: number;
+    groupPostsByCategory?: (posts: TPost[]) => unknown;
+}
+interface ArticleSource<TPost extends AsteroidArticlePost = AsteroidArticlePost, TDetail extends AsteroidArticlePagePost = AsteroidArticlePagePost> {
+    client: CmsServerClient;
+    schemaSlug: string;
+    listSelect: Select;
+    detailSelect: Select;
+    seo: AsteroidSeoConfig;
+    searchFields: string[];
+    status: ContentStatus;
+    articleType: ArticleJsonLdType;
+    relatedLimit: number;
+    groupPostsByCategory?: (posts: TPost[]) => unknown;
+}
+declare function buildSearchConditions(fields: string[], query?: string): CmsSearchCondition[] | undefined;
+declare function defineArticleSource<TPost extends AsteroidArticlePost = AsteroidArticlePost, TDetail extends AsteroidArticlePagePost = AsteroidArticlePagePost>(config: ArticleSourceConfig<TPost, TDetail>): ArticleSource<TPost, TDetail>;
+declare function fetchArticles<TPost extends AsteroidArticlePost = AsteroidArticlePost>(source: ArticleSource<TPost>, opts?: {
+    searchQuery?: string;
+    categorySlug?: string;
+    limit?: number;
+}): Promise<TPost[]>;
+declare function fetchArticle<TDetail extends AsteroidArticlePagePost = AsteroidArticlePagePost>(source: ArticleSource<AsteroidArticlePost, TDetail>, slug: string): Promise<TDetail | null>;
+declare function fetchRelatedArticles<TDetail extends AsteroidArticlePagePost = AsteroidArticlePagePost>(source: ArticleSource<AsteroidArticlePost, TDetail>, post: TDetail, slug: string): Promise<TDetail[]>;
+
+interface ArticlesListingRenderProps<TPost extends AsteroidArticlePost = AsteroidArticlePost> {
+    eyebrow?: ReactNode;
+    title?: ReactNode;
+    description?: ReactNode;
+    renderRoot?: (params: {
+        children: ReactNode;
+    }) => ReactNode;
+    renderHeader?: (params: AsteroidArticlesHeaderParams) => ReactNode;
+    renderFeaturedCard?: (params: AsteroidArticlesFeaturedCardParams<TPost>) => ReactNode;
+    renderPostCard: (params: AsteroidArticlesPostCardParams<TPost>) => ReactNode;
+    renderCategoryHeading?: (params: AsteroidArticlesCategoryHeadingParams<TPost>) => ReactNode;
+    renderPostGrid?: (params: AsteroidArticlesPostGridParams<TPost>) => ReactNode;
+    renderCategoryGroup?: (params: AsteroidArticlesCategoryGroupParams<TPost>) => ReactNode;
+    renderSkeleton?: () => ReactNode;
+    renderEmpty?: (params: AsteroidArticlesEmptyParams) => ReactNode;
+    renderContent?: (params: AsteroidArticlesContentParams) => ReactNode;
+}
+
+interface AsteroidArticlesListingServerProps<TPost extends AsteroidArticlePost = AsteroidArticlePost> extends ArticlesListingRenderProps<TPost> {
+    source: ArticleSource<TPost>;
+    searchQuery?: string;
+    categorySlug?: string;
+    articleSlug?: string;
+    searchParamKey?: string;
+    limit?: number;
+    noindex?: boolean;
+    searchBoxProps?: Omit<ArticleSearchBoxProps, "paramKey">;
+    renderSearch?: (params: AsteroidArticlesSearchParams) => ReactNode;
+    renderJsonLd?: (state: ArticlesViewState<TPost>) => ReactNode;
+    groupPostsByCategory?: (posts: TPost[]) => AsteroidArticleCategoryGroup<TPost>[];
+}
+declare function AsteroidArticlesListingServer<TPost extends AsteroidArticlePost = AsteroidArticlePost>(props: AsteroidArticlesListingServerProps<TPost>): Promise<react_jsx_runtime.JSX.Element>;
+
+interface AsteroidArticlePageServerProps<TDetail extends AsteroidArticlePagePost = AsteroidArticlePagePost> extends ArticleBodyRenderProps<TDetail> {
+    source: ArticleSource<AsteroidArticlePagePost, TDetail>;
+    slug: string;
+    articleType?: ArticleJsonLdType;
+    noindex?: boolean;
+    renderError?: (params: {
+        error?: unknown;
+        reason: "error" | "not-found";
+    }) => ReactNode;
+    renderJsonLd?: (params: {
+        post: TDetail;
+    }) => ReactNode;
+}
+declare function AsteroidArticlePageServer<TDetail extends AsteroidArticlePagePost = AsteroidArticlePagePost>(props: AsteroidArticlePageServerProps<TDetail>): Promise<react_jsx_runtime.JSX.Element>;
+
+declare function generateListingMetadata(source: ArticleSource, options?: {
+    categoryName?: string;
+    categorySlug?: string;
+    noindex?: boolean;
+}): Promise<Metadata>;
+declare function generateArticleMetadata(source: ArticleSource<AsteroidArticlePost, AsteroidArticlePagePost>, paramsOrSlug: string | {
+    slug: string;
+} | Promise<{
+    slug: string;
+}>): Promise<Metadata>;
+
+export { type ArticleSource, type ArticleSourceConfig, AsteroidArticlePageServer, type AsteroidArticlePageServerProps, AsteroidArticlesListingServer, type AsteroidArticlesListingServerProps, type CmsServerClient, type CmsServerClientConfig, buildSearchConditions, createCmsServerClient, defineArticleSource, fetchArticle, fetchArticles, fetchRelatedArticles, generateArticleMetadata, generateListingMetadata };