@businessdash/sdk 0.9.60 → 0.9.80

package/src/blog-core/index.ts

@@ -0,0 +1,423 @@
+/**
+ * `@businessdash/sdk/blog` — the headless blog controller.
+ *
+ * ## Why this exists
+ *
+ * Blog was the last surface that was iframe-only on EVERY binding, React
+ * included. `<Blog>` renders a BusinessDash-hosted page in a sandbox, which
+ * works but puts our markup inside your site — and for a blog specifically that
+ * is the worst place to lose control, because the content is the thing search
+ * engines and readers came for and it sits behind an iframe boundary.
+ *
+ * This is the native path: the post list, a single post, categories, tags,
+ * comments and likes as data. You render it, in your own layout, on your own
+ * URLs.
+ *
+ * Same contract as `createFormController`, `createStoreController` and
+ * `createChatController`: `snapshot()`, `subscribe()` (which does NOT replay),
+ * `destroy()`, and actions.
+ *
+ * @module
+ */
+
+import type {
+	BlogCategory,
+	BlogCommentPostInput,
+	BlogPostBySlugResponse,
+	BlogPublicComment,
+	BlogPublicPost,
+	BlogTagListResponse,
+} from "../contracts.js";
+
+/** Tags have no standalone contract type; take it from the list response. */
+export type BlogTag = BlogTagListResponse["items"][number];
+
+/** Structural client surface, so a proxy or a test double works unchanged. */
+export type BlogCoreClient = {
+	blog: {
+		listPosts(input?: {
+			limit?: number;
+			cursor?: number | null;
+			categoryId?: string;
+		}): Promise<{ items: BlogPublicPost[]; nextCursor: number | null }>;
+		getPost(slug: string): Promise<BlogPostBySlugResponse>;
+		listCategories(): Promise<{ items: BlogCategory[] }>;
+		listTags(): Promise<{ items: BlogTag[] }>;
+		listComments(
+			slug: string,
+			input?: { limit?: number; cursor?: number | null },
+		): Promise<{ items: BlogPublicComment[]; nextCursor: number | null }>;
+		postComment(slug: string, input: BlogCommentPostInput): Promise<unknown>;
+		likeStatus(slug: string): Promise<{ liked: boolean; likesCount: number }>;
+		toggleLike(slug: string): Promise<{ liked: boolean; likesCount: number }>;
+	};
+};
+
+export type BlogStatus = "idle" | "loading" | "ready" | "error";
+
+/** Field names are STABLE and load-bearing for every framework binding. */
+export type BlogSnapshot = {
+	status: BlogStatus;
+	posts: readonly BlogPublicPost[];
+	categories: readonly BlogCategory[];
+	tags: readonly BlogTag[];
+	/** The post opened via `openPost()`, if any. */
+	activePost: BlogPostBySlugResponse | null;
+	/** Comments for `activePost`. Empty until `loadComments()` runs. */
+	comments: readonly BlogPublicComment[];
+	/** Like state for `activePost`. */
+	liked: boolean;
+	likesCount: number;
+	categoryId: string | null;
+	hasMore: boolean;
+	hasMoreComments: boolean;
+	error: Error | null;
+	pending: {
+		posts: boolean;
+		post: boolean;
+		comments: boolean;
+		like: boolean;
+	};
+};
+
+export type BlogController = {
+	snapshot(): BlogSnapshot;
+	subscribe(callback: (snapshot: BlogSnapshot) => void): () => void;
+	/** Fetch the first page of posts, plus categories and tags. */
+	load(): Promise<void>;
+	loadMore(): Promise<void>;
+	filterByCategory(categoryId: string | null): Promise<void>;
+	/** Load a post by slug into `activePost`, with its like state. */
+	openPost(slug: string): Promise<void>;
+	closePost(): void;
+	loadComments(): Promise<void>;
+	loadMoreComments(): Promise<void>;
+	postComment(input: BlogCommentPostInput): Promise<void>;
+	toggleLike(): Promise<void>;
+	destroy(): void;
+};
+
+export type CreateBlogControllerOptions = {
+	client: BlogCoreClient;
+	/** Posts per page. Default 12. */
+	pageSize?: number;
+	/** Comments per page. Default 20. */
+	commentPageSize?: number;
+	categoryId?: string | null;
+	onError?: (error: Error) => void;
+};
+
+const DEFAULT_PAGE_SIZE = 12;
+const DEFAULT_COMMENT_PAGE_SIZE = 20;
+
+function toError(cause: unknown, fallback: string): Error {
+	return cause instanceof Error ? cause : new Error(fallback);
+}
+
+export function createBlogController(
+	options: CreateBlogControllerOptions,
+): BlogController {
+	const { client, onError } = options;
+	const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+	const commentPageSize = options.commentPageSize ?? DEFAULT_COMMENT_PAGE_SIZE;
+
+	let destroyed = false;
+	let cursor: number | null = null;
+	let commentCursor: number | null = null;
+	/** Same stale-response guard as the store: see `store-core`. */
+	let postsToken = 0;
+	/**
+	 * Separate token for the post detail. Opening post A then post B before A
+	 * resolves must not leave A's body under B's title — and the comments and
+	 * like state that follow must belong to whichever post actually won.
+	 */
+	let postToken = 0;
+
+	const subscribers = new Set<(s: BlogSnapshot) => void>();
+
+	const state: {
+		status: BlogStatus;
+		posts: BlogPublicPost[];
+		categories: BlogCategory[];
+		tags: BlogTag[];
+		activePost: BlogPostBySlugResponse | null;
+		activeSlug: string | null;
+		comments: BlogPublicComment[];
+		liked: boolean;
+		likesCount: number;
+		categoryId: string | null;
+		hasMore: boolean;
+		hasMoreComments: boolean;
+		error: Error | null;
+		pending: BlogSnapshot["pending"];
+	} = {
+		status: "idle",
+		posts: [],
+		categories: [],
+		tags: [],
+		activePost: null,
+		activeSlug: null,
+		comments: [],
+		liked: false,
+		likesCount: 0,
+		categoryId: options.categoryId ?? null,
+		hasMore: false,
+		hasMoreComments: false,
+		error: null,
+		pending: { posts: false, post: false, comments: false, like: false },
+	};
+
+	let cached: BlogSnapshot | null = null;
+
+	function snapshot(): BlogSnapshot {
+		if (!cached) {
+			cached = {
+				status: state.status,
+				posts: state.posts,
+				categories: state.categories,
+				tags: state.tags,
+				activePost: state.activePost,
+				comments: state.comments,
+				liked: state.liked,
+				likesCount: state.likesCount,
+				categoryId: state.categoryId,
+				hasMore: state.hasMore,
+				hasMoreComments: state.hasMoreComments,
+				error: state.error,
+				pending: state.pending,
+			};
+		}
+		return cached;
+	}
+
+	function notify(): void {
+		if (destroyed) return;
+		cached = null;
+		const next = snapshot();
+		for (const cb of subscribers) cb(next);
+	}
+
+	function fail(cause: unknown, fallback: string): void {
+		const error = toError(cause, fallback);
+		state.error = error;
+		if (state.status !== "ready") state.status = "error";
+		onError?.(error);
+	}
+
+	async function fetchPosts(append: boolean): Promise<void> {
+		const token = ++postsToken;
+		state.pending.posts = true;
+		if (!append) state.error = null;
+		notify();
+		try {
+			const page = await client.blog.listPosts({
+				limit: pageSize,
+				...(append && cursor !== null ? { cursor } : {}),
+				...(state.categoryId ? { categoryId: state.categoryId } : {}),
+			});
+			if (destroyed || token !== postsToken) return;
+			state.posts = append ? [...state.posts, ...page.items] : page.items;
+			cursor = page.nextCursor;
+			state.hasMore = page.nextCursor !== null;
+			state.status = "ready";
+		} catch (cause) {
+			if (destroyed || token !== postsToken) return;
+			fail(cause, "Failed to load posts.");
+		} finally {
+			if (!destroyed && token === postsToken) {
+				state.pending.posts = false;
+				notify();
+			}
+		}
+	}
+
+	async function fetchComments(append: boolean): Promise<void> {
+		const slug = state.activeSlug;
+		if (!slug) return;
+		const token = postToken;
+		state.pending.comments = true;
+		notify();
+		try {
+			const page = await client.blog.listComments(slug, {
+				limit: commentPageSize,
+				...(append && commentCursor !== null ? { cursor: commentCursor } : {}),
+			});
+			// The reader may have navigated to another post mid-request.
+			if (destroyed || token !== postToken) return;
+			state.comments = append ? [...state.comments, ...page.items] : page.items;
+			commentCursor = page.nextCursor;
+			state.hasMoreComments = page.nextCursor !== null;
+		} catch (cause) {
+			if (destroyed || token !== postToken) return;
+			fail(cause, "Failed to load comments.");
+		} finally {
+			if (!destroyed && token === postToken) {
+				state.pending.comments = false;
+				notify();
+			}
+		}
+	}
+
+	return {
+		snapshot,
+
+		subscribe(callback) {
+			subscribers.add(callback);
+			return () => {
+				subscribers.delete(callback);
+			};
+		},
+
+		async load() {
+			if (destroyed) return;
+			if (state.status === "idle") state.status = "loading";
+			notify();
+
+			// Taxonomy is independent of the post page, so it goes out alongside
+			// rather than after. Neither failing should hide the other.
+			const taxonomy = Promise.all([
+				client.blog
+					.listCategories()
+					.then((res) => {
+						if (!destroyed) state.categories = res.items;
+					})
+					.catch((cause) => {
+						if (!destroyed) fail(cause, "Failed to load categories.");
+					}),
+				client.blog
+					.listTags()
+					.then((res) => {
+						if (!destroyed) state.tags = res.items;
+					})
+					.catch((cause) => {
+						if (!destroyed) fail(cause, "Failed to load tags.");
+					}),
+			]);
+
+			await Promise.all([fetchPosts(false), taxonomy]);
+			if (!destroyed) notify();
+		},
+
+		async loadMore() {
+			if (destroyed || !state.hasMore || state.pending.posts) return;
+			await fetchPosts(true);
+		},
+
+		async filterByCategory(categoryId) {
+			if (destroyed) return;
+			state.categoryId = categoryId;
+			cursor = null;
+			await fetchPosts(false);
+		},
+
+		async openPost(slug) {
+			if (destroyed) return;
+			const token = ++postToken;
+			state.pending.post = true;
+			state.error = null;
+			// Clear the previous post's comments and like state immediately, so a
+			// slow fetch can't briefly show the last post's discussion under the
+			// new post's title.
+			state.comments = [];
+			state.liked = false;
+			state.likesCount = 0;
+			commentCursor = null;
+			state.activeSlug = slug;
+			notify();
+
+			try {
+				const post = await client.blog.getPost(slug);
+				if (destroyed || token !== postToken) return;
+				state.activePost = post;
+
+				// Like state is decorative; a failure here must not blank the post.
+				try {
+					const like = await client.blog.likeStatus(slug);
+					if (!destroyed && token === postToken) {
+						state.liked = like.liked;
+						state.likesCount = like.likesCount;
+					}
+				} catch {
+					// leave the defaults
+				}
+			} catch (cause) {
+				if (destroyed || token !== postToken) return;
+				fail(cause, "Failed to load the post.");
+			} finally {
+				if (!destroyed && token === postToken) {
+					state.pending.post = false;
+					notify();
+				}
+			}
+		},
+
+		closePost() {
+			if (destroyed) return;
+			postToken += 1; // orphan any in-flight detail request
+			state.activePost = null;
+			state.activeSlug = null;
+			state.comments = [];
+			state.liked = false;
+			state.likesCount = 0;
+			commentCursor = null;
+			notify();
+		},
+
+		loadComments() {
+			return fetchComments(false);
+		},
+
+		async loadMoreComments() {
+			if (destroyed || !state.hasMoreComments || state.pending.comments) return;
+			await fetchComments(true);
+		},
+
+		async postComment(input) {
+			const slug = state.activeSlug;
+			if (destroyed || !slug) return;
+			state.pending.comments = true;
+			state.error = null;
+			notify();
+			try {
+				await client.blog.postComment(slug, input);
+				if (destroyed) return;
+				// Re-read rather than splice the response in: a comment may be held
+				// for moderation, and inventing an approved-looking one locally
+				// would tell the reader something untrue.
+				commentCursor = null;
+				await fetchComments(false);
+			} catch (cause) {
+				if (!destroyed) {
+					fail(cause, "Failed to post the comment.");
+					state.pending.comments = false;
+					notify();
+				}
+			}
+		},
+
+		async toggleLike() {
+			const slug = state.activeSlug;
+			if (destroyed || !slug) return;
+			state.pending.like = true;
+			notify();
+			try {
+				const res = await client.blog.toggleLike(slug);
+				if (destroyed) return;
+				state.liked = res.liked;
+				state.likesCount = res.likesCount;
+			} catch (cause) {
+				if (!destroyed) fail(cause, "Failed to update the like.");
+			} finally {
+				if (!destroyed) {
+					state.pending.like = false;
+					notify();
+				}
+			}
+		},
+
+		destroy() {
+			destroyed = true;
+			subscribers.clear();
+		},
+	};
+}

package/src/blog.ts

@@ -0,0 +1,11 @@
+/**
+ * `@businessdash/sdk/blog` — the framework-agnostic blog core.
+ *
+ * Bindings shipped as SOURCE import through this public subpath rather than a
+ * relative path, so the consumer's bundler resolves it exactly as their own
+ * code would. `forms`, `store` and `chat` work the same way.
+ *
+ * @module
+ */
+
+export * from "./blog-core/index.js";