@btst/stack 1.0.1 → 1.1.1

package/src/plugins/blog/db.ts

@@ -0,0 +1,90 @@
+import { createDbPlugin } from "@btst/db";
+
+/**
+ * Blog plugin schema
+ * Defines the database table for blog posts
+ */
+export const blogSchema = createDbPlugin("blog", {
+	post: {
+		modelName: "post",
+		fields: {
+			title: {
+				type: "string",
+				required: true,
+			},
+			content: {
+				type: "string",
+				required: true,
+			},
+			excerpt: {
+				type: "string",
+				defaultValue: "",
+			},
+			slug: {
+				type: "string",
+				required: true,
+				unique: true,
+			},
+			image: {
+				type: "string",
+				required: false,
+			},
+			published: {
+				type: "boolean",
+				defaultValue: false,
+			},
+			publishedAt: {
+				type: "date",
+				required: false,
+			},
+			authorId: {
+				type: "string",
+				required: false,
+			},
+			createdAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+			updatedAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+		},
+	},
+	tag: {
+		modelName: "tag",
+		fields: {
+			name: {
+				type: "string",
+				required: true,
+				unique: true,
+			},
+			slug: {
+				type: "string",
+				required: true,
+				unique: true,
+			},
+			createdAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+			updatedAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+		},
+	},
+	postTag: {
+		modelName: "postTag",
+		fields: {
+			postId: {
+				type: "string",
+				required: true,
+			},
+			tagId: {
+				type: "string",
+				required: true,
+			},
+		},
+	},
+});

package/src/plugins/blog/query-keys.ts

@@ -0,0 +1,267 @@
+import {
+	mergeQueryKeys,
+	createQueryKeys,
+} from "@lukemorales/query-key-factory";
+import type { BlogApiRouter } from "./api";
+import { createApiClient } from "@btst/stack/plugins/client";
+import type { SerializedPost, SerializedTag } from "./types";
+
+interface PostsListParams {
+	query?: string;
+	limit?: number;
+	published?: boolean;
+	tagSlug?: string;
+}
+
+// Type guard for better-call error responses
+// better-call client returns Error$1<unknown> | Data<T>
+// We check if error exists and is not null/undefined to determine it's an error response
+function isErrorResponse(
+	response: unknown,
+): response is { error: unknown; data?: never } {
+	return (
+		typeof response === "object" &&
+		response !== null &&
+		"error" in response &&
+		response.error !== null &&
+		response.error !== undefined
+	);
+}
+
+// Helper to convert error to a proper Error object with meaningful message
+function toError(error: unknown): Error {
+	if (error instanceof Error) {
+		return error;
+	}
+
+	// Handle object errors (likely from better-call APIError)
+	if (typeof error === "object" && error !== null) {
+		// Try to extract message from common error object structures
+		const errorObj = error as Record<string, unknown>;
+		const message =
+			(typeof errorObj.message === "string" ? errorObj.message : null) ||
+			(typeof errorObj.error === "string" ? errorObj.error : null) ||
+			JSON.stringify(error);
+
+		const err = new Error(message);
+		// Preserve other properties
+		Object.assign(err, error);
+		return err;
+	}
+
+	// Fallback for primitive values
+	return new Error(String(error));
+}
+
+export function createBlogQueryKeys(
+	client: ReturnType<typeof createApiClient<BlogApiRouter>>,
+) {
+	const posts = createPostsQueries(client);
+	const drafts = createDraftsQueries(client);
+	const tags = createTagsQueries(client);
+
+	return mergeQueryKeys(posts, drafts, tags);
+}
+
+function createPostsQueries(
+	client: ReturnType<typeof createApiClient<BlogApiRouter>>,
+) {
+	return createQueryKeys("posts", {
+		list: (params?: PostsListParams) => ({
+			queryKey: [
+				{
+					query:
+						params?.query !== undefined && params?.query?.trim() === ""
+							? undefined
+							: params?.query,
+					limit: params?.limit ?? 10,
+					published: params?.published ?? true,
+					tagSlug: params?.tagSlug,
+				},
+			],
+			queryFn: async ({ pageParam }: { pageParam?: number }) => {
+				try {
+					const response = await client("/posts", {
+						method: "GET",
+						query: {
+							query: params?.query,
+							offset: pageParam ?? 0,
+							limit: params?.limit ?? 10,
+							published:
+								params?.published !== undefined
+									? params.published
+										? "true"
+										: "false"
+									: undefined,
+							tagSlug: params?.tagSlug,
+						},
+					});
+					// Check for errors (better-call returns Error$1<unknown> | Data<Post[]>)
+					if (isErrorResponse(response)) {
+						const errorResponse = response as { error: unknown };
+						throw toError(errorResponse.error);
+					}
+					// Type narrowed to Data<Post[]> after error check
+					return ((response as { data?: unknown }).data ??
+						[]) as unknown as SerializedPost[];
+				} catch (error) {
+					// Re-throw errors so React Query can catch them
+					throw error;
+				}
+			},
+		}),
+
+		// Simplified detail query
+		detail: (slug: string) => ({
+			queryKey: [slug],
+			queryFn: async () => {
+				if (!slug) return null;
+
+				try {
+					const response = await client("/posts", {
+						method: "GET",
+						query: { slug, limit: 1 },
+					});
+					// Check for errors (better-call returns Error$1<unknown> | Data<Post[]>)
+					if (isErrorResponse(response)) {
+						const errorResponse = response as { error: unknown };
+						throw toError(errorResponse.error);
+					}
+					// Type narrowed to Data<Post[]> after error check
+					const dataResponse = response as { data?: unknown[] };
+					return (dataResponse.data?.[0] ??
+						null) as unknown as SerializedPost | null;
+				} catch (error) {
+					// Re-throw errors so React Query can catch them
+					throw error;
+				}
+			},
+		}),
+
+		// Next/previous posts query
+		nextPrevious: (date: Date | string) => ({
+			queryKey: ["nextPrevious", date],
+			queryFn: async () => {
+				const dateValue = typeof date === "string" ? new Date(date) : date;
+				const response = await client("/posts/next-previous", {
+					method: "GET",
+					query: {
+						date: dateValue.toISOString(),
+					},
+				});
+				// Check for errors (better-call returns Error$1<unknown> | Data<...>)
+				if (isErrorResponse(response)) {
+					const errorResponse = response as { error: unknown };
+					throw toError(errorResponse.error);
+				}
+				// Type narrowed to Data<...> after error check
+				const dataResponse = response as { data?: unknown };
+				return dataResponse.data as {
+					previous: SerializedPost | null;
+					next: SerializedPost | null;
+				};
+			},
+		}),
+
+		// Recent posts query (separate from main list to avoid cache conflicts)
+		recent: (params?: { limit?: number; excludeSlug?: string }) => ({
+			queryKey: ["recent", params],
+			queryFn: async () => {
+				try {
+					const response = await client("/posts", {
+						method: "GET",
+						query: {
+							limit: params?.limit ?? 5,
+							published: "true",
+						},
+					});
+					// Check for errors (better-call returns Error$1<unknown> | Data<Post[]>)
+					if (isErrorResponse(response)) {
+						const errorResponse = response as { error: unknown };
+						throw toError(errorResponse.error);
+					}
+					// Type narrowed to Data<Post[]> after error check
+					let posts = ((response as { data?: unknown }).data ??
+						[]) as unknown as SerializedPost[];
+
+					// Exclude current post if specified
+					if (params?.excludeSlug) {
+						posts = posts.filter((post) => post.slug !== params.excludeSlug);
+					}
+
+					return posts;
+				} catch (error) {
+					// Re-throw errors so React Query can catch them
+					throw error;
+				}
+			},
+		}),
+	});
+}
+
+function createDraftsQueries(
+	client: ReturnType<typeof createApiClient<BlogApiRouter>>,
+) {
+	return createQueryKeys("drafts", {
+		list: (params?: PostsListParams) => ({
+			queryKey: [
+				{
+					...(params?.limit && { limit: params.limit }),
+				},
+			],
+			queryFn: async ({ pageParam }: { pageParam?: number }) => {
+				try {
+					const response = await client("/posts", {
+						method: "GET",
+						query: {
+							query: params?.query,
+							offset: pageParam ?? 0,
+							limit: params?.limit ?? 10,
+							published: "false",
+						},
+					});
+					// Check for errors (better-call returns Error$1<unknown> | Data<Post[]>)
+					if (isErrorResponse(response)) {
+						const errorResponse = response as { error: unknown };
+						throw toError(errorResponse.error);
+					}
+					// Type narrowed to Data<Post[]> after error check
+					return ((response as { data?: unknown }).data ??
+						[]) as unknown as SerializedPost[];
+				} catch (error) {
+					// Re-throw errors so React Query can catch them
+					throw error;
+				}
+			},
+		}),
+	});
+}
+
+function createTagsQueries(
+	client: ReturnType<typeof createApiClient<BlogApiRouter>>,
+) {
+	return createQueryKeys("tags", {
+		list: () => ({
+			queryKey: ["tags"],
+			queryFn: async () => {
+				try {
+					const response = await client("/tags", {
+						method: "GET",
+					});
+					// Check for errors (better-call returns Error$1<unknown> | Data<Tag[]>)
+					if (isErrorResponse(response)) {
+						const errorResponse = response as { error: unknown };
+						throw toError(errorResponse.error);
+					}
+					// Type narrowed to Data<Tag[]> after error check
+					// The API returns serialized tags (dates as strings)
+					return ((response as { data?: unknown }).data ??
+						[]) as unknown as SerializedTag[];
+				} catch (error) {
+					// Re-throw errors so React Query can catch them
+					throw error;
+				}
+			},
+		}),
+	});
+}

package/src/plugins/blog/schemas.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+const dateFields = {
+	publishedAt: z.coerce.date().optional(),
+	createdAt: z.coerce.date().optional(),
+	updatedAt: z.coerce.date().optional(),
+};
+
+const coreFields = {
+	title: z.string().min(1, "Title is required"),
+	content: z.string().min(1, "Content is required"),
+	excerpt: z.string().min(1, "Excerpt is required"),
+	image: z.string().optional(),
+	published: z.boolean().optional().default(false),
+	slug: z.string().min(1, "Slug is required"),
+	tags: z
+		.array(
+			z.union([
+				z.object({ name: z.string() }),
+				z.object({ id: z.string(), name: z.string(), slug: z.string() }),
+			]),
+		)
+		.optional()
+		.default([]),
+};
+
+export const PostDomainSchema = z.object({
+	id: z.string().optional(),
+	...coreFields,
+	...dateFields,
+});
+
+export const createPostSchema = PostDomainSchema.extend({
+	slug: PostDomainSchema.shape.slug.optional(),
+}).omit({ id: true }); // no id on create
+
+export const updatePostSchema = PostDomainSchema.extend({
+	id: z.string(), // required on update
+});

package/src/plugins/blog/style.css

@@ -0,0 +1,22 @@
+@import "./client.css";
+
+/*
+ * Blog Plugin CSS - Includes Tailwind class scanning
+ * 
+ * When consumed from npm, Tailwind v4 will automatically scan this package's
+ * source files for Tailwind classes. Consumers only need:
+ *   @import "@btst/stack/plugins/blog/css";
+ */
+
+/* Scan this package's source files for Tailwind classes */
+@source "../../../src/**/*.{ts,tsx}";
+
+/* Scan UI package components (if in monorepo) */
+@source "../../../../@workspace/ui/src/**/*.{ts,tsx}";
+
+/* Scan UI package components (if installed as npm package) */
+@source "../../../node_modules/@workspace/ui/src/**/*.{ts,tsx}";
+
+/*
+* alternatively consumer can use @source "../node_modules/@btst/stack/src/**\/*.{ts,tsx}";
+*/

package/src/plugins/blog/types.ts

@@ -0,0 +1,37 @@
+export type Post = {
+	id: string;
+	authorId?: string;
+	defaultLocale?: string;
+	slug: string;
+	title: string;
+	content: string;
+	excerpt: string;
+	image?: string;
+	published: boolean;
+	status?: "DRAFT" | "PUBLISHED";
+	tags: Tag[];
+	publishedAt?: Date;
+	createdAt: Date;
+	updatedAt: Date;
+};
+
+export type Tag = {
+	id: string;
+	slug: string;
+	name: string;
+	createdAt: Date;
+	updatedAt: Date;
+};
+
+export interface SerializedPost
+	extends Omit<Post, "createdAt" | "updatedAt" | "publishedAt" | "tags"> {
+	tags: SerializedTag[];
+	publishedAt?: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
+	createdAt: string;
+	updatedAt: string;
+}

package/src/plugins/blog/utils.ts

@@ -0,0 +1,144 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+import slug from "slug";
+
+export function slugify(text: string, locale: string = "en"): string {
+	return slug(text, { lower: true, locale });
+}
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}
+
+// Simple, dependency-free throttle with cancel/flush helpers
+// Behavior: leading and trailing enabled by default
+export function throttle<Args extends unknown[]>(
+	callback: (...args: Args) => void,
+	waitMs: number,
+) {
+	let timerId: ReturnType<typeof setTimeout> | null = null;
+	let lastInvokeTime = 0;
+	let trailingArgs: Args | null = null;
+
+	const invoke = (args: Args) => {
+		lastInvokeTime = Date.now();
+		callback(...args);
+	};
+
+	const throttled = (...args: Args) => {
+		const now = Date.now();
+		const remaining = waitMs - (now - lastInvokeTime);
+
+		// Leading edge
+		if (lastInvokeTime === 0) {
+			invoke(args);
+			return;
+		}
+
+		if (remaining <= 0 || remaining > waitMs) {
+			if (timerId) {
+				clearTimeout(timerId);
+				timerId = null;
+			}
+			invoke(args);
+		} else {
+			// Schedule trailing edge
+			trailingArgs = args;
+			if (!timerId) {
+				timerId = setTimeout(() => {
+					timerId = null;
+					if (trailingArgs) {
+						invoke(trailingArgs);
+						trailingArgs = null;
+					}
+				}, remaining);
+			}
+		}
+	};
+
+	throttled.cancel = () => {
+		if (timerId) {
+			clearTimeout(timerId);
+			timerId = null;
+		}
+		trailingArgs = null;
+		lastInvokeTime = 0;
+	};
+
+	throttled.flush = () => {
+		if (timerId && trailingArgs) {
+			clearTimeout(timerId);
+			timerId = null;
+			invoke(trailingArgs);
+			trailingArgs = null;
+		}
+	};
+
+	return throttled as ((...args: Args) => void) & {
+		cancel: () => void;
+		flush: () => void;
+	};
+}
+
+export function stripHtml(html: string): string {
+	// Remove HTML tags
+	let text = html.replace(/<[^>]*>/g, "");
+
+	// Decode common HTML entities
+	text = text
+		.replace(/&amp;/g, "&")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&#x27;/g, "'")
+		.replace(/&#x2F;/g, "/")
+		.replace(/&nbsp;/g, " ")
+		.replace(/&hellip;/g, "...");
+
+	// Clean up extra whitespace and newlines
+	return text.replace(/\s+/g, " ").trim();
+}
+
+export function stripMarkdown(markdown: string): string {
+	let text = markdown;
+
+	// Remove headers (# ## ### etc.)
+	text = text.replace(/^#{1,6}\s+/gm, "");
+
+	// Remove bold and italic (**text**, *text*, __text__, _text_)
+	text = text.replace(/\*\*([^*]+)\*\*/g, "$1");
+	text = text.replace(/\*([^*]+)\*/g, "$1");
+	text = text.replace(/__([^_]+)__/g, "$1");
+	text = text.replace(/_([^_]+)_/g, "$1");
+
+	// Remove strikethrough (~~text~~)
+	text = text.replace(/~~([^~]+)~~/g, "$1");
+
+	// Remove inline code (`code`)
+	text = text.replace(/`([^`]+)`/g, "$1");
+
+	// Remove code blocks (```code```)
+	text = text.replace(/```[\s\S]*?```/g, "");
+
+	// Remove links [text](url) -> text
+	text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+
+	// Remove images ![alt](url)
+	text = text.replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1");
+
+	// Remove blockquotes (> text)
+	text = text.replace(/^>\s+/gm, "");
+
+	// Remove horizontal rules (--- or ***)
+	text = text.replace(/^[-*]{3,}$/gm, "");
+
+	// Remove list markers (- * + and numbered lists)
+	text = text.replace(/^[\s]*[-*+]\s+/gm, "");
+	text = text.replace(/^[\s]*\d+\.\s+/gm, "");
+
+	// Clean up extra whitespace and newlines
+	return text
+		.replace(/\n\s*\n/g, "\n")
+		.replace(/\s+/g, " ")
+		.trim();
+}

package/src/plugins/client/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Plugin utilities and types for building standalone plugins
+ *
+ * This module exports everything needed to create custom plugins
+ * for Better Stack outside of this package.
+ *
+ * Note: Backend and Client plugins are separate to prevent SSR issues
+ * and enable better code splitting. Import them separately:
+ * - Backend: import type { BackendPlugin } from "@btst/stack/plugins/api"
+ * - Client: import type { ClientPlugin } from "@btst/stack/plugins/client"
+ */
+
+import type { ClientPlugin } from "../../types";
+
+export type {
+	ClientPlugin,
+	PluginOverrides,
+} from "../../types";
+
+export { createApiClient } from "../utils";
+
+// Re-export Yar types needed for plugins
+export type { Route } from "@btst/yar";
+export { createRoute, createRouter } from "@btst/yar";
+
+export { createClient } from "better-call/client";
+
+/**
+ * Helper to define a client plugin with full type inference
+ *
+ * Automatically infers route keys, hook names, and their types without needing casts.
+ *
+ * @example
+ * ```ts
+ * const messagesPlugin = defineClientPlugin({
+ *   name: "messages",
+ *   routes: () => ({
+ *     messagesList: createRoute("/messages", () => ({ ... }))
+ *   }),
+ *   hooks: () => ({
+ *     useMessages: () => { ... }
+ *   })
+ * });
+ * // No casts needed - route keys, hook names, and types are all preserved!
+ * ```
+ *
+ * @template TPlugin - The exact plugin definition (auto-inferred)
+ */
+export function defineClientPlugin<TPlugin extends ClientPlugin<any, any>>(
+	plugin: TPlugin,
+): TPlugin {
+	return plugin;
+}

package/src/plugins/utils.ts

@@ -0,0 +1,35 @@
+import { createClient } from "better-call/client";
+import type { Router, Endpoint } from "better-call";
+
+interface CreateApiClientOptions {
+	baseURL?: string;
+	basePath?: string;
+}
+
+/**
+ * Creates a Better Call API client with proper URL handling for both server and client side
+ * @param options - Configuration options
+ * @param options.baseURL - The base URL (e.g., 'http://localhost:3000'). If not provided, uses relative URLs (same domain)
+ * @param options.basePath - The API base path (defaults to '/')
+ * @template TRouter - The router type (Router or Record<string, Endpoint>)
+ */
+export function createApiClient<
+	TRouter extends Router | Record<string, Endpoint> = Record<string, Endpoint>,
+>(options?: CreateApiClientOptions): ReturnType<typeof createClient<TRouter>> {
+	const { baseURL = "", basePath = "/" } = options ?? {};
+
+	// Normalize baseURL - remove trailing slash if present
+	const normalizedBaseURL = baseURL ? baseURL.replace(/\/$/, "") : "";
+	// Normalize basePath - ensure it starts with / and doesn't end with /
+	const normalizedBasePath = basePath.startsWith("/")
+		? basePath
+		: `/${basePath}`;
+	const finalBasePath = normalizedBasePath.replace(/\/$/, "");
+
+	// If baseURL is not provided, apiPath is just the basePath (same domain, relative URL)
+	const apiPath = normalizedBaseURL + finalBasePath;
+
+	return createClient<TRouter>({
+		baseURL: apiPath,
+	});
+}