@btst/stack 1.5.1 → 1.6.0

package/src/plugins/form-builder/query-keys.ts

@@ -0,0 +1,198 @@
+import {
+	mergeQueryKeys,
+	createQueryKeys,
+} from "@lukemorales/query-key-factory";
+import type { FormBuilderApiRouter } from "./api";
+import { createApiClient } from "@btst/stack/plugins/client";
+import type {
+	SerializedForm,
+	PaginatedForms,
+	PaginatedFormSubmissions,
+	SerializedFormSubmissionWithData,
+} from "./types";
+
+interface FormListParams {
+	status?: "active" | "inactive" | "archived";
+	limit?: number;
+	offset?: number;
+}
+
+interface SubmissionListParams {
+	formId: string;
+	limit?: number;
+	offset?: number;
+}
+
+// Type guard for better-call error responses
+function isErrorResponse(
+	response: unknown,
+): response is { error: unknown; data?: never } {
+	if (typeof response !== "object" || response === null) {
+		return false;
+	}
+	const obj = response as Record<string, unknown>;
+	return "error" in obj && obj.error !== null && obj.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;
+	}
+
+	if (typeof error === "object" && error !== null) {
+		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);
+		Object.assign(err, error);
+		return err;
+	}
+
+	return new Error(String(error));
+}
+
+/**
+ * Create Form Builder query keys for React Query
+ * Used by consumers to fetch forms and submissions
+ */
+export function createFormBuilderQueryKeys(
+	client: ReturnType<typeof createApiClient<FormBuilderApiRouter>>,
+	headers?: HeadersInit,
+) {
+	const forms = createFormsQueries(client, headers);
+	const submissions = createSubmissionsQueries(client, headers);
+
+	return mergeQueryKeys(forms, submissions);
+}
+
+function createFormsQueries(
+	client: ReturnType<typeof createApiClient<FormBuilderApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createQueryKeys("forms", {
+		list: (params: FormListParams = {}) => ({
+			queryKey: ["list", params],
+			queryFn: async () => {
+				try {
+					const response: unknown = await client("/forms", {
+						method: "GET",
+						query: {
+							status: params.status,
+							limit: params.limit ?? 20,
+							offset: params.offset ?? 0,
+						},
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return (response as { data?: unknown }).data as PaginatedForms;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+
+		bySlug: (slug: string) => ({
+			queryKey: ["bySlug", slug],
+			queryFn: async () => {
+				if (!slug) return null;
+
+				try {
+					const response: unknown = await client("/forms/:slug", {
+						method: "GET",
+						params: { slug },
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return (response as { data?: unknown }).data as SerializedForm | null;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+
+		byId: (id: string) => ({
+			queryKey: ["byId", id],
+			queryFn: async () => {
+				if (!id) return null;
+
+				try {
+					const response: unknown = await client("/forms/id/:id", {
+						method: "GET",
+						params: { id },
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return (response as { data?: unknown }).data as SerializedForm | null;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+	});
+}
+
+function createSubmissionsQueries(
+	client: ReturnType<typeof createApiClient<FormBuilderApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createQueryKeys("formSubmissions", {
+		list: (params: SubmissionListParams) => ({
+			queryKey: [params],
+			queryFn: async () => {
+				try {
+					const response: unknown = await client("/forms/:formId/submissions", {
+						method: "GET",
+						params: { formId: params.formId },
+						query: {
+							limit: params.limit ?? 20,
+							offset: params.offset ?? 0,
+						},
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return (response as { data?: unknown })
+						.data as PaginatedFormSubmissions;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+
+		detail: (formId: string, subId: string) => ({
+			queryKey: [formId, subId],
+			queryFn: async () => {
+				if (!formId || !subId) return null;
+
+				try {
+					const response: unknown = await client(
+						"/forms/:formId/submissions/:subId",
+						{
+							method: "GET",
+							params: { formId, subId },
+							headers,
+						},
+					);
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return (response as { data?: unknown })
+						.data as SerializedFormSubmissionWithData | null;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+	});
+}

package/src/plugins/form-builder/schemas.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+
+/**
+ * Schema for listing forms with pagination
+ */
+export const listFormsQuerySchema = z.object({
+	status: z.enum(["active", "inactive", "archived"]).optional(),
+	limit: z.coerce.number().min(1).max(100).optional().default(20),
+	offset: z.coerce.number().min(0).optional().default(0),
+});
+
+/**
+ * Schema for creating a form
+ */
+export const createFormSchema = z.object({
+	name: z.string().min(1, "Name is required"),
+	slug: z.string().min(1, "Slug is required"),
+	description: z.string().optional(),
+	schema: z.string().min(1, "Schema is required"),
+	successMessage: z.string().optional(),
+	redirectUrl: z.string().url().optional().or(z.literal("")),
+	status: z
+		.enum(["active", "inactive", "archived"])
+		.optional()
+		.default("active"),
+});
+
+/**
+ * Schema for updating a form
+ */
+export const updateFormSchema = z.object({
+	name: z.string().min(1, "Name is required").optional(),
+	slug: z.string().min(1, "Slug is required").optional(),
+	description: z.string().optional(),
+	schema: z.string().min(1, "Schema is required").optional(),
+	successMessage: z.string().optional(),
+	redirectUrl: z.string().url().optional().or(z.literal("")),
+	status: z.enum(["active", "inactive", "archived"]).optional(),
+});
+
+/**
+ * Schema for form response
+ */
+export const formResponseSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	slug: z.string(),
+	description: z.string().nullable().optional(),
+	schema: z.string(),
+	successMessage: z.string().nullable().optional(),
+	redirectUrl: z.string().nullable().optional(),
+	status: z.string(),
+	createdBy: z.string().nullable().optional(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+});
+
+/**
+ * Schema for paginated forms response
+ */
+export const paginatedFormsResponseSchema = z.object({
+	items: z.array(formResponseSchema),
+	total: z.number(),
+	limit: z.number(),
+	offset: z.number(),
+});
+
+/**
+ * Schema for listing form submissions with pagination
+ */
+export const listSubmissionsQuerySchema = z.object({
+	limit: z.coerce.number().min(1).max(100).optional().default(20),
+	offset: z.coerce.number().min(0).optional().default(0),
+});
+
+/**
+ * Schema for submitting a form (public)
+ */
+export const submitFormSchema = z.object({
+	// Use passthrough object for dynamic form data validation
+	data: z.object({}).passthrough(),
+});
+
+/**
+ * Schema for form submission response
+ */
+export const formSubmissionResponseSchema = z.object({
+	id: z.string(),
+	formId: z.string(),
+	data: z.string(),
+	submittedAt: z.string(),
+	submittedBy: z.string().nullable().optional(),
+	ipAddress: z.string().nullable().optional(),
+	userAgent: z.string().nullable().optional(),
+});
+
+/**
+ * Schema for form submission with parsed data response
+ */
+export const formSubmissionWithDataResponseSchema =
+	formSubmissionResponseSchema.extend({
+		// Use passthrough object for dynamic parsed data
+		parsedData: z.object({}).passthrough(),
+		form: formResponseSchema.optional(),
+	});
+
+/**
+ * Schema for paginated submissions response
+ */
+export const paginatedSubmissionsResponseSchema = z.object({
+	items: z.array(formSubmissionWithDataResponseSchema),
+	total: z.number(),
+	limit: z.number(),
+	offset: z.number(),
+});
+
+// Export inferred types
+export type ListFormsQuery = z.infer<typeof listFormsQuerySchema>;
+export type CreateFormInput = z.infer<typeof createFormSchema>;
+export type UpdateFormInput = z.infer<typeof updateFormSchema>;
+export type ListSubmissionsQuery = z.infer<typeof listSubmissionsQuerySchema>;
+export type SubmitFormInput = z.infer<typeof submitFormSchema>;

package/src/plugins/form-builder/style.css

@@ -0,0 +1,19 @@
+@import "./client.css";
+
+/*
+ * Form Builder 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/form-builder/css";
+ */
+
+/* Scan this package's source files for Tailwind classes */
+@source "../../../src/**/*.{ts,tsx}";
+
+/* Scan UI package components (when installed as npm package the UI package will be in this dir) */
+@source "../../packages/ui/src";
+
+/*
+* alternatively consumer can use @source "../node_modules/@btst/stack/src/**\/*.{ts,tsx}";
+*/

package/src/plugins/form-builder/types.ts

@@ -0,0 +1,317 @@
+/**
+ * Form Builder Plugin Types
+ *
+ * Key distinction from CMS Plugin:
+ * - CMS uses developer-defined Zod schemas in code
+ * - Form Builder allows non-technical admins to build forms via drag-and-drop UI
+ * - Forms are serialized to/from JSON Schema for storage
+ */
+
+/**
+ * Form stored in the database
+ */
+export type Form = {
+	id: string;
+	/** Display name for the form */
+	name: string;
+	/** URL-friendly slug - unique identifier for public access */
+	slug: string;
+	/** Optional description for admin UI */
+	description?: string;
+	/** JSON Schema stored as string (includes steps, fieldType, stepGroup, etc.) */
+	schema: string;
+	/** Optional custom success message after submission */
+	successMessage?: string;
+	/** Optional redirect URL after submission */
+	redirectUrl?: string;
+	/** Form status: active, inactive, archived */
+	status: "active" | "inactive" | "archived";
+	/** User who created the form */
+	createdBy?: string;
+	createdAt: Date;
+	updatedAt: Date;
+};
+
+/**
+ * Form submission stored in the database
+ */
+export type FormSubmission = {
+	id: string;
+	/** Reference to the form */
+	formId: string;
+	/** Submitted data as JSON string */
+	data: string;
+	/** Submission timestamp */
+	submittedAt: Date;
+	/** Optional user ID if authenticated */
+	submittedBy?: string;
+	/** Client IP address for rate limiting and spam protection */
+	ipAddress?: string;
+	/** User agent for analytics */
+	userAgent?: string;
+};
+
+/**
+ * Form submission with its parent form joined
+ */
+export type FormSubmissionWithForm = FormSubmission & {
+	form?: Form;
+};
+
+/**
+ * Serialized form for API responses (dates as strings)
+ */
+export interface SerializedForm
+	extends Omit<Form, "createdAt" | "updatedAt" | "status"> {
+	status: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+/**
+ * Serialized form submission for API responses (dates as strings)
+ */
+export interface SerializedFormSubmission
+	extends Omit<FormSubmission, "submittedAt"> {
+	submittedAt: string;
+}
+
+/**
+ * Serialized form submission with parsed data
+ */
+export interface SerializedFormSubmissionWithData<
+	TData = Record<string, unknown>,
+> extends SerializedFormSubmission {
+	/** Parsed data object (JSON.parse of data field) */
+	parsedData: TData;
+	/** Joined form */
+	form?: SerializedForm;
+}
+
+/**
+ * Paginated list response for forms
+ */
+export interface PaginatedForms {
+	items: SerializedForm[];
+	total: number;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Paginated list response for form submissions
+ */
+export interface PaginatedFormSubmissions<TData = Record<string, unknown>> {
+	items: SerializedFormSubmissionWithData<TData>[];
+	total: number;
+	limit: number;
+	offset: number;
+}
+
+// ============================================================================
+// BACKEND HOOKS
+// ============================================================================
+
+/**
+ * Context passed to all backend hooks
+ */
+export interface FormBuilderHookContext {
+	/** User ID if authenticated */
+	userId?: string;
+	/** Request headers */
+	headers?: Headers;
+	/** Client IP address (for rate limiting) */
+	ipAddress?: string;
+	/** User agent string */
+	userAgent?: string;
+}
+
+/**
+ * Context for submission-specific hooks
+ */
+export interface SubmissionHookContext extends FormBuilderHookContext {
+	/** Form slug being submitted */
+	formSlug: string;
+	/** Form ID */
+	formId: string;
+}
+
+/**
+ * Input data for creating a form
+ */
+export interface FormInput {
+	name: string;
+	slug: string;
+	description?: string;
+	schema: string;
+	successMessage?: string;
+	redirectUrl?: string;
+	status?: "active" | "inactive" | "archived";
+	createdBy?: string;
+}
+
+/**
+ * Input data for updating a form
+ */
+export interface FormUpdate {
+	name?: string;
+	slug?: string;
+	description?: string;
+	schema?: string;
+	successMessage?: string;
+	redirectUrl?: string;
+	status?: "active" | "inactive" | "archived";
+}
+
+/**
+ * Backend hooks for Form Builder plugin
+ *
+ * All CRUD hooks receive ipAddress and headers for auth/rate limiting.
+ * Return false from onBefore* hooks to reject the operation (throws 403).
+ */
+export interface FormBuilderBackendHooks {
+	// ============================================================================
+	// FORM CRUD HOOKS (Admin operations)
+	// ============================================================================
+
+	/** Called before listing forms. Return false to deny access (403). */
+	onBeforeListForms?: (
+		ctx: FormBuilderHookContext,
+	) => Promise<boolean> | boolean;
+
+	/** Called before creating a form. Return false to deny, or modified data. */
+	onBeforeFormCreated?: (
+		data: FormInput,
+		ctx: FormBuilderHookContext,
+	) => Promise<FormInput | false> | FormInput | false;
+
+	/** Called after a form is created */
+	onAfterFormCreated?: (
+		form: SerializedForm,
+		ctx: FormBuilderHookContext,
+	) => Promise<void> | void;
+
+	/** Called before getting a form by ID or slug. Return false to deny access. */
+	onBeforeGetForm?: (
+		idOrSlug: string,
+		ctx: FormBuilderHookContext,
+	) => Promise<boolean> | boolean;
+
+	/** Called before updating a form. Return false to deny, or modified data. */
+	onBeforeFormUpdated?: (
+		id: string,
+		data: FormUpdate,
+		ctx: FormBuilderHookContext,
+	) => Promise<FormUpdate | false> | FormUpdate | false;
+
+	/** Called after a form is updated */
+	onAfterFormUpdated?: (
+		form: SerializedForm,
+		ctx: FormBuilderHookContext,
+	) => Promise<void> | void;
+
+	/** Called before deleting a form. Return false to deny. */
+	onBeforeFormDeleted?: (
+		id: string,
+		ctx: FormBuilderHookContext,
+	) => Promise<boolean> | boolean;
+
+	/** Called after a form is deleted */
+	onAfterFormDeleted?: (
+		id: string,
+		ctx: FormBuilderHookContext,
+	) => Promise<void> | void;
+
+	// ============================================================================
+	// SUBMISSION HOOKS (Public form submissions)
+	// ============================================================================
+
+	/**
+	 * Called before processing a form submission.
+	 * Use for: spam protection, rate limiting, data validation/enrichment.
+	 *
+	 * @returns false to reject submission (400), or modified data to continue
+	 */
+	onBeforeSubmission?: (
+		formSlug: string,
+		data: Record<string, unknown>,
+		ctx: SubmissionHookContext,
+	) =>
+		| Promise<Record<string, unknown> | false>
+		| Record<string, unknown>
+		| false;
+
+	/**
+	 * Called after a submission is saved.
+	 * Use for: sending emails, storing in CRM, triggering workflows.
+	 */
+	onAfterSubmission?: (
+		submission: SerializedFormSubmission,
+		form: SerializedForm,
+		ctx: SubmissionHookContext,
+	) => Promise<void> | void;
+
+	/** Called when a submission fails */
+	onSubmissionError?: (
+		error: Error,
+		formSlug: string,
+		data: Record<string, unknown>,
+		ctx: SubmissionHookContext,
+	) => Promise<void> | void;
+
+	// ============================================================================
+	// SUBMISSIONS MANAGEMENT HOOKS (Admin viewing submissions)
+	// ============================================================================
+
+	/** Called before listing submissions. Return false to deny access (403). */
+	onBeforeListSubmissions?: (
+		formId: string,
+		ctx: FormBuilderHookContext,
+	) => Promise<boolean> | boolean;
+
+	/** Called before getting a submission. Return false to deny access. */
+	onBeforeGetSubmission?: (
+		submissionId: string,
+		ctx: FormBuilderHookContext,
+	) => Promise<boolean> | boolean;
+
+	/** Called before deleting a submission. Return false to deny. */
+	onBeforeSubmissionDeleted?: (
+		submissionId: string,
+		ctx: FormBuilderHookContext,
+	) => Promise<boolean> | boolean;
+
+	/** Called after a submission is deleted */
+	onAfterSubmissionDeleted?: (
+		submissionId: string,
+		ctx: FormBuilderHookContext,
+	) => Promise<void> | void;
+
+	// ============================================================================
+	// ERROR HOOK
+	// ============================================================================
+
+	/** Called on any error */
+	onError?: (
+		error: Error,
+		operation:
+			| "list"
+			| "get"
+			| "create"
+			| "update"
+			| "delete"
+			| "submit"
+			| "listSubmissions"
+			| "getSubmission"
+			| "deleteSubmission",
+		ctx: FormBuilderHookContext,
+	) => Promise<void> | void;
+}
+
+/**
+ * Configuration for the Form Builder backend plugin
+ */
+export interface FormBuilderBackendConfig {
+	/** Optional hooks for customizing behavior */
+	hooks?: FormBuilderBackendHooks;
+}

package/src/plugins/form-builder/utils.ts

@@ -0,0 +1,63 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+import slug from "slug";
+
+/**
+ * Converts text to a URL-friendly slug
+ */
+export function slugify(text: string, locale: string = "en"): string {
+	return slug(text, { lower: true, locale });
+}
+
+/**
+ * Merges class names using clsx and tailwind-merge
+ */
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}
+
+/**
+ * Safely parses JSON with a fallback
+ */
+export function safeJsonParse<T>(json: string, fallback: T): T {
+	try {
+		return JSON.parse(json) as T;
+	} catch {
+		return fallback;
+	}
+}
+
+/**
+ * Extracts client IP address from request headers
+ * Handles common proxy headers
+ */
+export function extractIpAddress(headers?: Headers): string | undefined {
+	if (!headers) return undefined;
+
+	// Check common proxy headers in order of preference
+	const forwardedFor = headers.get("x-forwarded-for");
+	if (forwardedFor) {
+		// x-forwarded-for can contain multiple IPs, take the first one
+		return forwardedFor.split(",")[0]?.trim();
+	}
+
+	const realIp = headers.get("x-real-ip");
+	if (realIp) {
+		return realIp.trim();
+	}
+
+	const cfConnectingIp = headers.get("cf-connecting-ip");
+	if (cfConnectingIp) {
+		return cfConnectingIp.trim();
+	}
+
+	return undefined;
+}
+
+/**
+ * Extracts user agent from request headers
+ */
+export function extractUserAgent(headers?: Headers): string | undefined {
+	if (!headers) return undefined;
+	return headers.get("user-agent") || undefined;
+}