@dsaplatform/content-sdk 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# @dsaplatform/content-sdk
+
+React SDK for **DSA Content Operating System** — fetch and render SEO-optimized content from a central content engine on any Next.js or React site.
+
+## Installation
+
+```bash
+npm install @dsaplatform/content-sdk
+```
+
+## Quick Start — Next.js App Router (SSR)
+
+### 1. Server-side data fetching in `app/blog/[slug]/page.tsx`
+
+```tsx
+import { fetchArticleBySlug, fetchRelatedArticles, generateArticleMetadata } from '@dsaplatform/content-sdk/server';
+
+const config = {
+  apiUrl: process.env.CONTENT_ENGINE_URL!,
+  apiKey: process.env.CONTENT_API_KEY!,
+  cacheStrategy: 'revalidate' as const,
+  revalidateSeconds: 3600,
+};
+
+export async function generateMetadata({ params }: { params: { slug: string } }) {
+  const article = await fetchArticleBySlug(config, params.slug);
+  return generateArticleMetadata(article, 'https://yoursite.com');
+}
+
+export default async function BlogPost({ params }: { params: { slug: string } }) {
+  const article = await fetchArticleBySlug(config, params.slug);
+  const related = await fetchRelatedArticles(config, params.slug, 3);
+
+  return (
+    <ArticlePageWrapper article={article} related={related} />
+  );
+}
+```
+
+### 2. Client component for rendering
+
+```tsx
+'use client';
+import { ArticlePage, SeoMetaBridge } from '@dsaplatform/content-sdk';
+
+export function ArticlePageWrapper({ article, related }) {
+  return (
+    <>
+      <SeoMetaBridge article={article} siteUrl="https://yoursite.com" />
+      <ArticlePage
+        article={article}
+        showFaq
+        showTableOfContents
+        showRelated
+        relatedArticles={related}
+        onRelatedClick={(slug) => window.location.href = `/blog/${slug}`}
+      />
+    </>
+  );
+}
+```
+
+### 3. Article listing in `app/blog/page.tsx`
+
+```tsx
+import { fetchArticleList } from '@dsaplatform/content-sdk/server';
+import { ArticleFeed } from '@dsaplatform/content-sdk';
+
+export default async function BlogIndex() {
+  const { items } = await fetchArticleList(config, { page: 1, per_page: 12 });
+
+  return (
+    <ArticleFeed
+      articles={items}
+      layout="grid"
+      columns={3}
+      onArticleClick={(slug) => `/blog/${slug}`}
+    />
+  );
+}
+```
+
+## Client-Side Hooks (SPA / CSR)
+
+Wrap your app with the provider:
+
+```tsx
+import { DsaContentProvider } from '@dsaplatform/content-sdk';
+
+<DsaContentProvider config={{ apiUrl: '...', apiKey: '...' }}>
+  <App />
+</DsaContentProvider>
+```
+
+Then use hooks anywhere:
+
+```tsx
+import { useArticles, useArticle, useRelatedArticles, useCategories } from '@dsaplatform/content-sdk';
+
+function BlogList() {
+  const { articles, loading, pagination } = useArticles({ page: 1, per_page: 10 });
+  if (loading) return <p>Loading...</p>;
+  return <ArticleFeed articles={articles} />;
+}
+
+function BlogPost({ slug }: { slug: string }) {
+  const { article, loading } = useArticle(slug);
+  const { articles: related } = useRelatedArticles(slug, 3);
+  if (loading || !article) return <p>Loading...</p>;
+  return <ArticlePage article={article} showRelated relatedArticles={related} />;
+}
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `ArticleFeed` | Grid/list of article cards |
+| `ArticlePage` | Full article with TOC, FAQ, related |
+| `FaqBlock` | FAQ section with Schema.org markup |
+| `RelatedArticles` | Related articles widget |
+| `SeoMetaBridge` | JSON-LD structured data |
+
+## Server Helpers
+
+| Function | Description |
+|----------|-------------|
+| `fetchArticleBySlug(config, slug)` | Get one article |
+| `fetchArticleList(config, filters?)` | Paginated article list |
+| `fetchRelatedArticles(config, slug, limit?)` | Related articles |
+| `fetchCategories(config)` | Pillar/cluster tree |
+| `fetchSitemap(config)` | All published slugs |
+| `generateArticleMetadata(article, siteUrl?)` | Next.js Metadata object |
+
+## Configuration
+
+```typescript
+interface DsaContentConfig {
+  apiUrl: string;           // Content Engine URL
+  apiKey: string;           // Site's public API key
+  cacheStrategy?: 'no-cache' | 'force-cache' | 'revalidate';
+  revalidateSeconds?: number; // ISR interval
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,369 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * SDK Configuration for DSA Content Engine
+ */
+interface DsaContentConfig {
+    /** Content Engine API URL (e.g., "https://content.example.com") */
+    apiUrl: string;
+    /** Site's public API key for authentication */
+    apiKey: string;
+    /** Cache strategy for Next.js ISR */
+    cacheStrategy?: 'no-cache' | 'force-cache' | 'revalidate';
+    /** Revalidation interval in seconds (for ISR) */
+    revalidateSeconds?: number;
+}
+/**
+ * Full article response from Content Engine
+ */
+interface Article {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt: string | null;
+    content_html: string;
+    content_json: any | null;
+    h1: string | null;
+    meta_title: string | null;
+    meta_description: string | null;
+    canonical_url?: string | null;
+    target_keyword: string | null;
+    secondary_keywords: string[];
+    headings: ArticleHeading[];
+    faq: FaqItem[];
+    internal_links: InternalLink[];
+    schema_json: any | null;
+    featured_image_url: string | null;
+    featured_image_alt: string | null;
+    publish_status: string;
+    published_at: string | null;
+    updated_at?: string | null;
+    word_count: number | null;
+    reading_time_minutes: number | null;
+    seo_score: number | null;
+    pillar_name?: string;
+    cluster_name?: string;
+    content_type?: string;
+}
+/**
+ * Abbreviated article for lists
+ */
+interface ArticleListItem {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt: string | null;
+    featured_image_url: string | null;
+    featured_image_alt: string | null;
+    published_at: string | null;
+    pillar_name?: string;
+    cluster_name?: string;
+    content_type?: string;
+    reading_time_minutes: number | null;
+}
+/**
+ * Article heading (from H1-H6 tags)
+ */
+interface ArticleHeading {
+    level: number;
+    text: string;
+    id: string;
+}
+/**
+ * FAQ item
+ */
+interface FaqItem {
+    question: string;
+    answer: string;
+}
+/**
+ * Internal link reference
+ */
+interface InternalLink {
+    slug: string;
+    anchor_text: string;
+}
+/**
+ * Category with clusters
+ */
+interface Category {
+    id: string;
+    name: string;
+    description: string | null;
+    article_count: number;
+    clusters: ClusterInfo[];
+}
+/**
+ * Cluster information
+ */
+interface ClusterInfo {
+    id: string;
+    name: string;
+    description: string | null;
+    article_count: number;
+}
+/**
+ * Paginated response
+ */
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    per_page: number;
+    total_pages: number;
+}
+/**
+ * Filters for article list queries
+ */
+interface ArticleFilters {
+    page?: number;
+    per_page?: number;
+    pillar?: string;
+    cluster?: string;
+    content_type?: string;
+    search?: string;
+}
+/**
+ * Sitemap entry
+ */
+interface SitemapEntry {
+    slug: string;
+    title: string;
+    published_at: string;
+    updated_at: string;
+}
+/**
+ * Hook state for async data fetching
+ */
+interface UseArticlesState {
+    articles: ArticleListItem[];
+    loading: boolean;
+    error: Error | null;
+    pagination: {
+        page: number;
+        per_page: number;
+        total: number;
+        total_pages: number;
+    };
+}
+/**
+ * Hook state for single article
+ */
+interface UseArticleState {
+    article: Article | null;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Hook state for article list (related articles, etc.)
+ */
+interface UseArticleListState {
+    articles: ArticleListItem[];
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Hook state for categories
+ */
+interface UseCategoriesState {
+    categories: Category[];
+    loading: boolean;
+    error: Error | null;
+}
+
+/**
+ * ContentClient — HTTP client for DSA Content Engine Public API.
+ * Works in both Node.js (SSR) and browser environments.
+ */
+declare class ContentClient {
+    private apiUrl;
+    private apiKey;
+    private cacheStrategy;
+    private revalidateSeconds?;
+    constructor(config: DsaContentConfig);
+    private request;
+    /** Get paginated list of published articles */
+    getArticles(filters?: ArticleFilters): Promise<PaginatedResponse<ArticleListItem>>;
+    /** Get a single article by slug */
+    getArticleBySlug(slug: string): Promise<Article>;
+    /** Get related articles for a given slug */
+    getRelatedArticles(slug: string, limit?: number): Promise<ArticleListItem[]>;
+    /** Get all categories (pillars + clusters) with article counts */
+    getCategories(): Promise<Category[]>;
+    /** Get sitemap data for all published articles */
+    getSitemap(): Promise<SitemapEntry[]>;
+}
+
+interface DsaContentProviderProps {
+    config: DsaContentConfig;
+    children: React.ReactNode;
+}
+/**
+ * Wrap your app (or a subtree) with DsaContentProvider to enable
+ * the useDsaContent() hook and all data-fetching hooks.
+ *
+ * ```tsx
+ * <DsaContentProvider config={{ apiUrl: "...", apiKey: "..." }}>
+ *   <App />
+ * </DsaContentProvider>
+ * ```
+ */
+declare function DsaContentProvider({ config, children }: DsaContentProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the ContentClient instance from context.
+ * Must be called inside a DsaContentProvider.
+ */
+declare function useDsaContent(): ContentClient;
+
+/**
+ * Fetch a paginated list of published articles.
+ *
+ * ```tsx
+ * const { articles, loading, error, pagination } = useArticles({ page: 1, per_page: 10 });
+ * ```
+ */
+declare function useArticles(filters?: ArticleFilters): UseArticlesState & {
+    refetch: () => void;
+};
+/**
+ * Fetch a single article by slug.
+ *
+ * ```tsx
+ * const { article, loading, error } = useArticle("my-article-slug");
+ * ```
+ */
+declare function useArticle(slug: string | undefined): UseArticleState & {
+    refetch: () => void;
+};
+/**
+ * Fetch related articles for a given slug.
+ *
+ * ```tsx
+ * const { articles, loading } = useRelatedArticles("my-article-slug", 4);
+ * ```
+ */
+declare function useRelatedArticles(slug: string | undefined, limit?: number): UseArticleListState & {
+    refetch: () => void;
+};
+/**
+ * Fetch all categories (pillars + clusters).
+ *
+ * ```tsx
+ * const { categories, loading } = useCategories();
+ * ```
+ */
+declare function useCategories(): UseCategoriesState & {
+    refetch: () => void;
+};
+
+interface ArticleFeedProps {
+    articles: ArticleListItem[];
+    layout?: 'grid' | 'list';
+    columns?: 1 | 2 | 3;
+    showExcerpt?: boolean;
+    showImage?: boolean;
+    showMeta?: boolean;
+    onArticleClick?: (slug: string) => void;
+    className?: string;
+    renderArticle?: (article: ArticleListItem) => React.ReactNode;
+}
+/**
+ * Renders a grid or list of article cards.
+ *
+ * ```tsx
+ * <ArticleFeed articles={articles} layout="grid" columns={3} onArticleClick={(slug) => router.push(`/blog/${slug}`)} />
+ * ```
+ */
+declare function ArticleFeed({ articles, layout, columns, showExcerpt, showImage, showMeta, onArticleClick, className, renderArticle, }: ArticleFeedProps): react_jsx_runtime.JSX.Element;
+
+interface ArticlePageProps {
+    article: Article;
+    showFaq?: boolean;
+    showTableOfContents?: boolean;
+    showMeta?: boolean;
+    showRelated?: boolean;
+    relatedArticles?: ArticleListItem[];
+    onRelatedClick?: (slug: string) => void;
+    className?: string;
+    components?: {
+        H1?: React.ComponentType<{
+            children: React.ReactNode;
+        }>;
+        Toc?: React.ComponentType<{
+            headings: Article['headings'];
+        }>;
+        Faq?: React.ComponentType<{
+            items: FaqItem[];
+        }>;
+    };
+}
+/**
+ * Renders a full article page with optional TOC, FAQ, and related articles.
+ *
+ * ```tsx
+ * <ArticlePage article={article} showTableOfContents showFaq />
+ * ```
+ */
+declare function ArticlePage({ article, showFaq, showTableOfContents, showMeta, showRelated, relatedArticles, onRelatedClick, className, components, }: ArticlePageProps): react_jsx_runtime.JSX.Element;
+
+interface FaqBlockProps {
+    items: FaqItem[];
+    collapsible?: boolean;
+    defaultOpen?: boolean;
+    className?: string;
+    title?: string;
+}
+/**
+ * FAQ block with optional collapse behavior and Schema.org FAQPage markup.
+ *
+ * ```tsx
+ * <FaqBlock items={article.faq} collapsible />
+ * ```
+ */
+declare function FaqBlock({ items, collapsible, defaultOpen, className, title, }: FaqBlockProps): react_jsx_runtime.JSX.Element | null;
+
+interface RelatedArticlesProps {
+    articles: ArticleListItem[];
+    title?: string;
+    limit?: number;
+    onArticleClick?: (slug: string) => void;
+    className?: string;
+}
+/**
+ * Related articles widget.
+ *
+ * ```tsx
+ * <RelatedArticles articles={related} onArticleClick={(slug) => router.push(`/blog/${slug}`)} />
+ * ```
+ */
+declare function RelatedArticles({ articles, title, limit, onArticleClick, className, }: RelatedArticlesProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Generate Next.js App Router Metadata object from an Article.
+ * Use in page.tsx generateMetadata():
+ *
+ * ```ts
+ * import { generateArticleMetadata } from "@dsa/content-sdk/server";
+ *
+ * export async function generateMetadata({ params }) {
+ *   const article = await fetchArticleBySlug(config, params.slug);
+ *   return generateArticleMetadata(article, "https://example.com");
+ * }
+ * ```
+ */
+declare function generateArticleMetadata(article: Article, siteUrl?: string): Record<string, any>;
+/**
+ * Renders JSON-LD structured data for an article.
+ * Include this component in your article page layout for SEO.
+ *
+ * ```tsx
+ * <SeoMetaBridge article={article} siteUrl="https://example.com" />
+ * ```
+ */
+declare function SeoMetaBridge({ article, siteUrl, }: {
+    article: Article;
+    siteUrl?: string;
+}): react_jsx_runtime.JSX.Element;
+
+export { type Article, ArticleFeed, type ArticleFeedProps, type ArticleFilters, type ArticleHeading, type ArticleListItem, ArticlePage, type ArticlePageProps, type Category, type ClusterInfo, ContentClient, type DsaContentConfig, DsaContentProvider, type DsaContentProviderProps, FaqBlock, type FaqBlockProps, type FaqItem, type InternalLink, type PaginatedResponse, RelatedArticles, type RelatedArticlesProps, SeoMetaBridge, type SitemapEntry, type UseArticleListState, type UseArticleState, type UseArticlesState, type UseCategoriesState, generateArticleMetadata, useArticle, useArticles, useCategories, useDsaContent, useRelatedArticles };