appos 0.6.0-0 → 0.7.0-0

package/src/devtools/panel/modules/emails/spam-checker.ts

@@ -0,0 +1,231 @@
+/**
+ * Spam checking module using Postmark SpamCheck API.
+ *
+ * Uses the free Postmark SpamAssassin API to detect spam patterns in emails.
+ * No API key required.
+ */
+
+/**
+ * A single spam rule matched by SpamAssassin.
+ */
+export interface SpamRule {
+	/**
+	 * The SpamAssassin rule name.
+	 */
+	rule: string;
+
+	/**
+	 * Human-readable description of the rule.
+	 */
+	description: string;
+
+	/**
+	 * Points added to the spam score by this rule.
+	 */
+	score: number;
+}
+
+/**
+ * Result of spam checking an email.
+ */
+export interface SpamCheckResult {
+	/**
+	 * Whether the check was successful.
+	 */
+	success: boolean;
+
+	/**
+	 * The total spam score (lower is better, typically 5+ is spam).
+	 */
+	score: number;
+
+	/**
+	 * List of SpamAssassin rules that matched.
+	 */
+	rules: SpamRule[];
+
+	/**
+	 * Time taken to check in milliseconds.
+	 */
+	checkTime: number;
+
+	/**
+	 * Error message if the check failed.
+	 */
+	error?: string;
+}
+
+/**
+ * Postmark SpamCheck API response structure.
+ */
+interface PostmarkSpamResponse {
+	success: boolean;
+	score: string;
+	rules: Array<{
+		score: string;
+		description: string;
+	}>;
+	report?: string;
+}
+
+/**
+ * Constructs a raw email message from HTML and text content.
+ *
+ * SpamAssassin requires a full email message with headers and body.
+ * This creates a minimal MIME message for analysis.
+ *
+ * @param html - The HTML content of the email.
+ * @param text - The plain text content of the email.
+ * @param subject - Optional subject line.
+ * @returns Raw email message string.
+ */
+function constructRawEmail(
+	html: string,
+	text: string,
+	subject = "Test Email",
+): string {
+	const boundary = `----=_Part_${Date.now()}_${Math.random().toString(36).substring(2)}`;
+
+	const headers = [
+		"MIME-Version: 1.0",
+		"From: test@example.com",
+		"To: recipient@example.com",
+		`Subject: ${subject}`,
+		`Content-Type: multipart/alternative; boundary="${boundary}"`,
+		"",
+	].join("\r\n");
+
+	const textPart = [
+		`--${boundary}`,
+		"Content-Type: text/plain; charset=utf-8",
+		"Content-Transfer-Encoding: quoted-printable",
+		"",
+		text,
+	].join("\r\n");
+
+	const htmlPart = [
+		`--${boundary}`,
+		"Content-Type: text/html; charset=utf-8",
+		"Content-Transfer-Encoding: quoted-printable",
+		"",
+		html,
+	].join("\r\n");
+
+	const closing = `--${boundary}--`;
+
+	return [headers, textPart, htmlPart, closing].join("\r\n");
+}
+
+/**
+ * Checks email content for spam patterns using Postmark SpamCheck API.
+ *
+ * Algorithm:
+ * 1. Construct a raw MIME email from HTML and text content.
+ * 2. Send to Postmark's free SpamCheck API.
+ * 3. Parse the response and extract rules.
+ * 4. Return structured result with score and matched rules.
+ *
+ * @param html - The HTML content of the email.
+ * @param text - The plain text content of the email.
+ * @param subject - Optional subject line for the test email.
+ * @returns Spam check result with score and matched rules.
+ *
+ * @example
+ * ```typescript
+ * const result = await checkSpamScore(htmlContent, textContent);
+ * console.log(`Spam score: ${result.score}`);
+ * for (const rule of result.rules) {
+ *   console.log(`[${rule.score}] ${rule.description}`);
+ * }
+ * ```
+ */
+export async function checkSpamScore(
+	html: string,
+	text: string,
+	subject?: string,
+): Promise<SpamCheckResult> {
+	const start = performance.now();
+
+	try {
+		const rawEmail = constructRawEmail(html, text, subject);
+
+		const response = await fetch("https://spamcheck.postmarkapp.com/filter", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "application/json",
+			},
+			body: JSON.stringify({
+				email: rawEmail,
+				options: "long",
+			}),
+		});
+
+		if (!response.ok) {
+			return {
+				success: false,
+				score: 0,
+				rules: [],
+				checkTime: performance.now() - start,
+				error: `SpamCheck API returned ${response.status}`,
+			};
+		}
+
+		const data = (await response.json()) as PostmarkSpamResponse;
+
+		if (!data.success) {
+			return {
+				success: false,
+				score: 0,
+				rules: [],
+				checkTime: performance.now() - start,
+				error: "SpamCheck API returned unsuccessful response",
+			};
+		}
+
+		// Parse the rules from the report
+		const rules: SpamRule[] = data.rules.map((rule) => ({
+			rule: extractRuleName(rule.description),
+			description: cleanRuleDescription(rule.description),
+			score: Number.parseFloat(rule.score),
+		}));
+
+		return {
+			success: true,
+			score: Number.parseFloat(data.score),
+			rules,
+			checkTime: performance.now() - start,
+		};
+	} catch (error) {
+		return {
+			success: false,
+			score: 0,
+			rules: [],
+			checkTime: performance.now() - start,
+			error: error instanceof Error ? error.message : "Unknown error",
+		};
+	}
+}
+
+/**
+ * Extracts the rule name from a SpamAssassin rule description.
+ *
+ * @param description - The full rule description.
+ * @returns The rule name or "UNKNOWN".
+ */
+function extractRuleName(description: string): string {
+	// SpamAssassin rule names are usually the first word in uppercase
+	const match = /^([A-Z0-9_]+)/.exec(description.trim());
+	return match?.[1] ?? "UNKNOWN";
+}
+
+/**
+ * Cleans up a SpamAssassin rule description for display.
+ *
+ * @param description - The raw rule description.
+ * @returns Cleaned description.
+ */
+function cleanRuleDescription(description: string): string {
+	// Remove the rule name prefix if present
+	return description.replace(/^[A-Z0-9_]+\s*/, "").trim();
+}

package/src/{storybook → devtools/storybook}/.storybook/main.ts

@@ -11,17 +11,17 @@ import {
 	getStoredFontsConfig,
 	resolveFontConfig,
 	viteFontPlugin,
-} from "appos/vite";
+} from "appos/devtools/vite";
 import type { Plugin } from "vite";
 import { mergeConfig } from "vite";
 import {
 	type ParsedTheme,
 	parseThemeFromString,
-} from "../../web/lib/colors.ts";
+} from "../../../web/lib/colors.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const storybookDir = join(__dirname, "..");
-const apposRoot = join(__dirname, "../../..");
+const apposRoot = join(__dirname, "../../../..");
 const appRoot = process.cwd();
 const appName = `${process.env.APP_NAME || "AppOS"} Design System`;
 
@@ -142,6 +142,14 @@ export default {
 })();
 window.STORYBOOK_THEME = ${JSON.stringify(buildStorybookTheme(theme))};
 window.STORYBOOK_BRAND_TITLE = '<img src="/logo.png" alt="" style="height: 28px; margin-right: 4px; vertical-align: middle;" />' + ${JSON.stringify(appName)};
+</script>`,
+	previewHead: (head) => `${head}
+<link rel="icon" href="/favicon.ico" />
+<title>${appName}</title>
+<style>${fontCss}</style>
+<script>
+window.STORYBOOK_THEME = ${JSON.stringify(buildStorybookTheme(theme))};
+window.STORYBOOK_BRAND_TITLE = '<img src="/logo.png" alt="" style="height: 28px; margin-right: 4px; vertical-align: middle;" />' + ${JSON.stringify(appName)};
 </script>`,
 	staticDirs: [join(appRoot, "public")],
 	stories: [
@@ -187,8 +195,8 @@ window.STORYBOOK_BRAND_TITLE = '<img src="/logo.png" alt="" style="height: 28px;
 			resolve: {
 				alias: {
 					"#api": join(appRoot, "api"),
-					"#isomorphic": join(appRoot, "isomorphic"),
 					"#src": join(apposRoot, "src"),
+					"#universal": join(appRoot, "universal"),
 					"#web": join(appRoot, "web"),
 					"void-elements": join(storybookDir, "shims/void-elements.js"),
 				},

package/src/{storybook → devtools/storybook}/.storybook/manager.ts

@@ -2,7 +2,7 @@ import { addons } from "storybook/manager-api";
 import { create } from "storybook/theming";
 
 /** Storybook theme configuration from CSS variables. */
-interface StorybookTheme {
+export interface StorybookTheme {
 	base: "light" | "dark";
 	colorPrimary: string;
 	colorSecondary: string;

package/src/{storybook → devtools/storybook}/.storybook/preview.tsx

@@ -5,8 +5,11 @@ import { withThemeByClassName } from "@storybook/addon-themes";
 import type { Preview, ReactRenderer } from "@storybook/react";
 import i18n from "i18next";
 import { I18nextProvider, initReactI18next } from "react-i18next";
+import { create } from "storybook/theming";
 import { withRouter } from "storybook-addon-remix-react-router";
-import enUI from "../../web/ui/locales/en/ui.json";
+import enUI from "../../../web/ui/locales/en/ui.json";
+// Import to get Window.STORYBOOK_THEME declaration
+import type {} from "./manager.ts";
 
 // Initialize i18n synchronously for Storybook with bundled translations.
 i18n.use(initReactI18next).init({
@@ -64,6 +67,9 @@ export default {
 			 * nothing. It can be removed once the bug is fixed.
 			 */
 			container: DocsContainer,
+			theme: window.STORYBOOK_THEME
+				? create(window.STORYBOOK_THEME)
+				: undefined,
 			source: {
 				type: "dynamic",
 				excludeDecorators: true,

package/src/{storybook → devtools/storybook}/docs/Introduction.mdx

@@ -16,7 +16,9 @@ Explore foundations, components, and patterns that power your product.
 ## Usage
 
 ```tsx
-import { Button, Card, Input } from "appos/web";
+import { Button } from "appos/web/ui/button";
+import { Card } from "appos/web/ui/card";
+import { Input } from "appos/web/ui/input";
 
 function MyComponent() {
   return (

package/src/{web/client/auth-paths.ts → universal/auth.ts}

@@ -1,13 +1,43 @@
 /**
- * Client-safe authentication path utilities.
- *
- * This module contains auth path configuration and redirect utilities that are
- * safe to import in client-side code (no Node.js APIs).
- *
- * For route building (uses Node.js APIs), see routes/auth/utils.ts.
+ * Universal auth constants and types - no Node.js or browser-specific APIs.
  */
 import { redirect } from "react-router";
 
+/**
+ * Default base path for auth routes.
+ */
+export const AUTH_BASE_PATH = "/auth" as const;
+
+/**
+ * Default base URL (empty - same origin).
+ */
+export const AUTH_BASE_URL = "" as const;
+
+/**
+ * Array of all supported captcha providers.
+ * Use with z.enum() for config validation.
+ *
+ * @example
+ * ```ts
+ * CAPTCHA_PROVIDER: z.enum(captchaProviders).optional(),
+ * ```
+ */
+export const captchaProviders = [
+	"captchafox",
+	"cloudflare-turnstile",
+	"google-recaptcha",
+	"hcaptcha",
+] as const;
+
+/**
+ * Captcha provider type.
+ */
+export type CaptchaProvider = (typeof captchaProviders)[number];
+
+// ============================================================================
+// Auth Paths
+// ============================================================================
+
 /**
  * Configuration for authentication route paths.
  *
@@ -81,6 +111,10 @@ export const DEFAULT_AUTH_PATHS: AuthPaths = {
 	emailOtp: "/email-login",
 };
 
+// ============================================================================
+// Auth Redirect Utilities
+// ============================================================================
+
 /**
  * Creates a redirect response to the login page with the return URL preserved.
  *
@@ -146,3 +180,17 @@ export function definePostAuthRedirect(
 	const redirectTo = url.searchParams.get("redirect") || fallbackPath;
 	return redirect(redirectTo);
 }
+
+// ============================================================================
+// Auth Layout Types (used for config, no React runtime deps)
+// ============================================================================
+
+/**
+ * Available layout variants for authentication pages.
+ */
+export const authLayoutVariants = ["centered", "split", "minimal"] as const;
+
+/**
+ * Auth layout variant type.
+ */
+export type AuthLayoutVariant = (typeof authLayoutVariants)[number];